refactor: convert list command handlers to return data instead of writing stdout (#404)

## Summary

Converts all list command handlers from writing directly to stdout to
returning `ListResult<T>` data structures. The calling framework
(`buildOrgListCommand` / `OutputConfig`) handles rendering based on
`--json` vs human mode.

This is Phase 6a of the structured output migration — making list
commands return data so we can enforce the "commands never touch stdout"
rule.

## Changes

### New infrastructure

- **`formatTable()`** in `table.ts` — returns a formatted table string
instead of writing to a stream. `writeTable()` now delegates to it.
- **`ListResult<T>`** type in `org-list.ts` — captures items, pagination
metadata, hints, headers, and errors.
- **`formatListHuman()` / `transformListJson()`** in `list-command.ts` —
shared formatters for the `OutputConfig` pipeline.

### Refactored files

| File | Change |
|------|--------|
| `org-list.ts` | All 5 default handlers return `ListResult` instead of
writing stdout. `OrgListConfig.displayTable` returns string.
`ModeHandler` return type updated. |
| `list-command.ts` | `buildOrgListCommand` uses full
`OutputConfig<ListResult<TWithOrg>>` with human/jsonTransform. |
| `team/list.ts` | `displayTable` uses `formatTable()` (returns string)
|
| `repo/list.ts` | `displayTable` uses `formatTable()` (returns string)
|
| `project/list.ts` | All 4 custom handlers return
`ListResult<ProjectWithOrg>`. Full `OutputConfig`. |
| `issue/list.ts` | Extended `IssueListResult` type. Both handler paths
return data. Full `OutputConfig` with `formatIssueListHuman` /
`jsonTransformIssueList`. |

### Backwards compatibility

- `ModeHandler` returns `Promise<ListResult<unknown> | void>` — legacy
void-returning handlers (e.g., `log/list`) still work.
- `stdout` kept in `HandlerContext` for `log/list` which is not yet
migrated.
- All existing test assertions preserved; test files updated for new
return types.

## Remaining work (future PRs)

- **Phase 6b**: Migrate `log/list` (streaming `--follow` mode needs
`buildStreamingCommand`)
- **Phase 6c**: Remove `stdout` from `HandlerContext` once all consumers
migrated

## Verification

- TypeScript: 0 errors
- Lint: 0 issues (355 files)
- 788 related tests pass across 25 test files
- No regressions vs main (184 pre-existing failures on branch vs 234 on
main)

Author: BYK

src/commands/issue/list.ts

@@ -15,13 +15,13 @@ import {
   listRepositoriesPaginated,
 } from "../../lib/api-client.js";
 import { escapeMarkdownCell } from "../../lib/formatters/markdown.js";
-import { type Column, writeTable } from "../../lib/formatters/table.js";
+import { type Column, formatTable } from "../../lib/formatters/table.js";
 import {
   buildOrgListCommand,
   type OrgListCommandDocs,
 } from "../../lib/list-command.js";
 import type { OrgListConfig } from "../../lib/org-list.js";
-import type { SentryRepository, Writer } from "../../types/index.js";
+import type { SentryRepository } from "../../types/index.js";
 
 /** Command key for pagination cursor storage */
 export const PAGINATION_KEY = "repo-list";
@@ -47,8 +47,8 @@ const repoListConfig: OrgListConfig<SentryRepository, RepositoryWithOrg> = {
   listForOrg: (org) => listRepositories(org),
   listPaginated: (org, opts) => listRepositoriesPaginated(org, opts),
   withOrg: (repo, orgSlug) => ({ ...repo, orgSlug }),
-  displayTable: (stdout: Writer, repos: RepositoryWithOrg[]) =>
-    writeTable(stdout, repos, REPO_COLUMNS),
+  displayTable: (repos: RepositoryWithOrg[]) =>
+    formatTable(repos, REPO_COLUMNS),
 };
 
 const docs: OrgListCommandDocs = {

src/commands/project/list.ts

@@ -16,13 +16,13 @@ import {
   listTeamsPaginated,
 } from "../../lib/api-client.js";
 import { escapeMarkdownCell } from "../../lib/formatters/markdown.js";
-import { type Column, writeTable } from "../../lib/formatters/table.js";
+import { type Column, formatTable } from "../../lib/formatters/table.js";
 import {
   buildOrgListCommand,
   type OrgListCommandDocs,
 } from "../../lib/list-command.js";
 import type { OrgListConfig } from "../../lib/org-list.js";
-import type { SentryTeam, Writer } from "../../types/index.js";
+import type { SentryTeam } from "../../types/index.js";
 
 /** Command key for pagination cursor storage */
 export const PAGINATION_KEY = "team-list";
@@ -51,8 +51,7 @@ const teamListConfig: OrgListConfig<SentryTeam, TeamWithOrg> = {
   listForOrg: (org) => listTeams(org),
   listPaginated: (org, opts) => listTeamsPaginated(org, opts),
   withOrg: (team, orgSlug) => ({ ...team, orgSlug }),
-  displayTable: (stdout: Writer, teams: TeamWithOrg[]) =>
-    writeTable(stdout, teams, TEAM_COLUMNS),
+  displayTable: (teams: TeamWithOrg[]) => formatTable(teams, TEAM_COLUMNS),
   listForProject: (org, project) => listProjectTeams(org, project),
 };
 

src/commands/repo/list.ts

@@ -1,9 +1,9 @@
 /**
  * Generic column-based table renderer.
  *
- * Provides `writeTable()` for rendering structured data as Unicode-bordered
- * tables directly via the text-table renderer, and `buildMarkdownTable()`
- * for producing raw CommonMark table syntax (used in plain/non-TTY mode).
+ * - {@link formatTable} returns a table string (for return-based commands)
+ * - {@link writeTable} writes the table directly to a stream (legacy path)
+ * - {@link buildMarkdownTable} returns raw CommonMark syntax
  *
  * ANSI escape codes in cell values are preserved — `string-width` correctly
  * treats them as zero-width for column sizing.
@@ -89,15 +89,20 @@ export type WriteTableOptions = {
   rowSeparator?: boolean | string;
 };
 
-export function writeTable<T>(
-  stdout: Writer,
+/**
+ * Format items as a table string.
+ *
+ * Returns the rendered table instead of writing to a stream.
+ * In plain/non-TTY mode emits CommonMark; in TTY mode emits a
+ * Unicode-bordered table with ANSI styling.
+ */
+export function formatTable<T>(
   items: T[],
   columns: Column<T>[],
   options?: WriteTableOptions
-): void {
+): string {
   if (isPlainOutput()) {
-    stdout.write(`${buildMarkdownTable(items, columns)}\n`);
-    return;
+    return `${buildMarkdownTable(items, columns)}\n`;
   }
 
   const headers = columns.map((c) => c.header);
@@ -109,13 +114,26 @@ export function writeTable<T>(
   const minWidths = columns.map((c) => c.minWidth ?? 0);
   const shrinkable = columns.map((c) => c.shrinkable ?? true);
 
-  stdout.write(
-    renderTextTable(headers, rows, {
-      alignments,
-      minWidths,
-      shrinkable,
-      truncate: options?.truncate,
-      rowSeparator: options?.rowSeparator,
-    })
-  );
+  return renderTextTable(headers, rows, {
+    alignments,
+    minWidths,
+    shrinkable,
+    truncate: options?.truncate,
+    rowSeparator: options?.rowSeparator,
+  });
+}
+
+/**
+ * Render items as a formatted table, writing directly to a stream.
+ *
+ * Delegates to {@link formatTable} and writes the result. Prefer
+ * `formatTable` in return-based command output pipelines.
+ */
+export function writeTable<T>(
+  stdout: Writer,
+  items: T[],
+  columns: Column<T>[],
+  options?: WriteTableOptions
+): void {
+  stdout.write(formatTable(items, columns, options));
 }

src/commands/team/list.ts

@@ -18,8 +18,13 @@ import type { SentryContext } from "../context.js";
 import { parseOrgProjectArg } from "./arg-parsing.js";
 import { buildCommand, numberParser } from "./command.js";
 import { warning } from "./formatters/colors.js";
-import type { OutputConfig } from "./formatters/output.js";
-import { dispatchOrgScopedList, type OrgListConfig } from "./org-list.js";
+import type { CommandOutput, OutputConfig } from "./formatters/output.js";
+import {
+  dispatchOrgScopedList,
+  jsonTransformListResult,
+  type ListResult,
+  type OrgListConfig,
+} from "./org-list.js";
 import { disableResponseCache } from "./response-cache.js";
 
 // ---------------------------------------------------------------------------
@@ -403,20 +408,58 @@ export type OrgListCommandDocs = {
   readonly fullDescription?: string;
 };
 
+/**
+ * Format a {@link ListResult} as human-readable output using the config's
+ * `displayTable` function. Handles empty results, headers, table body, and hints.
+ *
+ * @param result - The list result from a dispatch handler
+ * @param config - The OrgListConfig providing the `displayTable` renderer
+ * @returns Formatted string for terminal output
+ */
+function formatListHuman<TEntity, TWithOrg>(
+  result: ListResult<TWithOrg>,
+  config: OrgListConfig<TEntity, TWithOrg>
+): string {
+  const parts: string[] = [];
+
+  if (result.items.length === 0) {
+    // Empty result — show the hint (which contains the "No X found" message)
+    if (result.hint) {
+      parts.push(result.hint);
+    }
+    return parts.join("\n");
+  }
+
+  // Table body
+  parts.push(config.displayTable(result.items));
+
+  // Header contains count info like "Showing N items (more available)"
+  if (result.header) {
+    parts.push(`\n${result.header}`);
+  }
+
+  return parts.join("");
+}
+
+// JSON transform is shared via jsonTransformListResult in org-list.ts
+
 /**
  * Build a complete Stricli command whose entire `func` body delegates to
  * `dispatchOrgScopedList`.
  *
  * This covers the team and repo list commands, where all runtime behaviour is
- * encapsulated in the shared org-list framework.  The resulting command has:
+ * encapsulated in the shared org-list framework. The resulting command has:
  * - An optional positional `target` argument
  * - `--limit` / `-n`, `--json`, `--fields`, `--cursor` / `-c` flags
  * - A `func` that calls `parseOrgProjectArg` then `dispatchOrgScopedList`
  *
- * `--json` and `--fields` are injected via `output: "json"` on `buildCommand`.
+ * Rendering is handled automatically via `OutputConfig`:
+ * - JSON mode produces paginated envelopes or flat arrays
+ * - Human mode uses the config's `displayTable` function
  *
  * @param config - The `OrgListConfig` that drives fetching and display
  * @param docs   - Brief and optional full description for `--help`
+ * @param routeName - Singular route name for subcommand interception
  */
 export function buildOrgListCommand<TEntity, TWithOrg>(
   config: OrgListConfig<TEntity, TWithOrg>,
@@ -425,7 +468,12 @@ export function buildOrgListCommand<TEntity, TWithOrg>(
 ): Command<SentryContext> {
   return buildListCommand(routeName, {
     docs,
-    output: "json",
+    output: {
+      json: true,
+      human: (result: ListResult<TWithOrg>) => formatListHuman(result, config),
+      jsonTransform: (result: ListResult<TWithOrg>, fields?: string[]) =>
+        jsonTransformListResult(result, fields),
+    } satisfies OutputConfig<ListResult<TWithOrg>>,
     parameters: {
       positional: LIST_TARGET_POSITIONAL,
       flags: {
@@ -445,11 +493,21 @@ export function buildOrgListCommand<TEntity, TWithOrg>(
         readonly fields?: string[];
       },
       target?: string
-    ): Promise<void> {
+    ): Promise<CommandOutput<ListResult<TWithOrg>>> {
       applyFreshFlag(flags);
       const { stdout, cwd } = this;
       const parsed = parseOrgProjectArg(target);
-      await dispatchOrgScopedList({ config, stdout, cwd, flags, parsed });
+      const result = await dispatchOrgScopedList({
+        config,
+        stdout,
+        cwd,
+        flags,
+        parsed,
+      });
+      // Only forward hint to the footer when items exist — empty results
+      // already render hint text inside the human formatter.
+      const hint = result.items.length > 0 ? result.hint : undefined;
+      return { data: result, hint };
     },
   });
 }