refactor: convert org-list handlers to return ListResult instead of writing stdout

All org-scoped list handlers now return ListResult<T> containing items +
metadata (hasMore, nextCursor, hint, errors, jsonExtra) instead of writing
directly to stdout. This enables callers (buildOrgListCommand) to handle
rendering via OutputConfig.

Changes:
- org-list.ts: All default handlers return ListResult, removed stdout params
  from handleOrgAll, handleAutoDetect, handleExplicitOrg,
  handleExplicitProject, handleProjectSearch
- list-command.ts: buildOrgListCommand uses OutputConfig with formatListHuman
  and jsonTransformList for automatic rendering
- project/list.ts: All 4 override handlers return ListResult<ProjectWithOrg>,
  command func returns CommandOutput<ListResult> with full OutputConfig
- issue/list.ts: handleOrgAllIssues and handleResolvedTargets return
  ListResult<SentryIssue> (still write to stdout internally due to complex
  rendering, but satisfy the ModeHandler return type contract)
- team/list.ts, repo/list.ts: displayTable returns string via formatTable
- formatters/table.ts: Added formatTable() returning string (writeTable
  delegates to it)

Test updates:
- org-list.test.ts: Assert on returned ListResult instead of stdout writes
- list-command.test.ts: dispatchSpy returns ListResult, buildOrgListCommand
  takes 3 args (config, docs, routeName), displayTable returns string
- project/list.test.ts: Handler tests use new signatures without stdout param

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 };
     },
   });
 }