feat(list): add pagination and consistent target parsing to all list commands

Author: BYK

src/commands/issue/list.ts

@@ -10,16 +10,27 @@ import { buildOrgAwareAliases } from "../../lib/alias.js";
 import {
   findProjectsBySlug,
   listIssues,
+  listIssuesPaginated,
   listProjects,
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
 import { buildCommand, numberParser } from "../../lib/command.js";
+import {
+  clearPaginationCursor,
+  getPaginationCursor,
+  setPaginationCursor,
+} from "../../lib/db/pagination.js";
 import {
   clearProjectAliases,
   setProjectAliases,
 } from "../../lib/db/project-aliases.js";
 import { createDsnFingerprint } from "../../lib/dsn/index.js";
-import { ApiError, AuthError, ContextError } from "../../lib/errors.js";
+import {
+  ApiError,
+  AuthError,
+  ContextError,
+  ValidationError,
+} from "../../lib/errors.js";
 import {
   divider,
   type FormatShortIdOptions,
@@ -32,17 +43,22 @@ import {
   type ResolvedTarget,
   resolveAllTargets,
 } from "../../lib/resolve-target.js";
+import { getApiBaseUrl } from "../../lib/sentry-client.js";
 import type {
   ProjectAliasEntry,
   SentryIssue,
   Writer,
 } from "../../types/index.js";
 
+/** Command key for pagination cursor storage */
+export const PAGINATION_KEY = "issue-list";
+
 type ListFlags = {
   readonly query?: string;
   readonly limit: number;
   readonly sort: "date" | "new" | "freq" | "user";
   readonly json: boolean;
+  readonly cursor?: string;
 };
 
 type SortValue = "date" | "new" | "freq" | "user";
@@ -429,8 +445,15 @@ export const listCommand = buildCommand({
         brief: "Output as JSON",
         default: false,
       },
+      cursor: {
+        kind: "parsed",
+        parse: String,
+        brief:
+          'Pagination cursor — only for <org>/ mode (use "last" to continue)',
+        optional: true,
+      },
     },
-    aliases: { q: "query", s: "sort", n: "limit" },
+    aliases: { q: "query", s: "sort", n: "limit", c: "cursor" },
   },
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: command entry point with inherent complexity
   async func(
@@ -443,6 +466,96 @@ export const listCommand = buildCommand({
     // Parse positional argument to determine resolution strategy
     const parsed = parseOrgProjectArg(target);
 
+    // Cursor pagination is only supported in org-all mode
+    if (flags.cursor && parsed.type !== "org-all") {
+      throw new ValidationError(
+        "The --cursor flag is only supported when listing issues for a specific organization " +
+          "(e.g., sentry issue list <org>/). " +
+          "Use 'sentry issue list <org>/' for paginated results.",
+        "cursor"
+      );
+    }
+
+    // Handle org-all mode with cursor pagination (different code path)
+    if (parsed.type === "org-all") {
+      const org = parsed.org;
+      const contextKey = `host:${getApiBaseUrl()}|type:org:${org}|sort:${flags.sort}${flags.query ? `|q:${flags.query}` : ""}`;
+      let cursor: string | undefined;
+      if (flags.cursor) {
+        if (flags.cursor === "last") {
+          const cached = getPaginationCursor(PAGINATION_KEY, contextKey);
+          if (!cached) {
+            throw new ContextError(
+              "Pagination cursor",
+              "No saved cursor for this query. Run without --cursor first."
+            );
+          }
+          cursor = cached;
+        } else {
+          cursor = flags.cursor;
+        }
+      }
+
+      setContext([org], []);
+
+      const response = await listIssuesPaginated(org, "", {
+        query: flags.query,
+        cursor,
+        perPage: flags.limit,
+        sort: flags.sort,
+      });
+
+      // Strip the project filter since we're listing org-wide (pass empty projectSlug)
+      // The API handles org-wide issue listing without a project filter
+
+      if (response.nextCursor) {
+        setPaginationCursor(PAGINATION_KEY, contextKey, response.nextCursor);
+      } else {
+        clearPaginationCursor(PAGINATION_KEY, contextKey);
+      }
+
+      const hasMore = !!response.nextCursor;
+
+      if (flags.json) {
+        const output = hasMore
+          ? {
+              data: response.data,
+              nextCursor: response.nextCursor,
+              hasMore: true,
+            }
+          : { data: response.data, hasMore: false };
+        writeJson(stdout, output);
+        return;
+      }
+
+      if (response.data.length === 0) {
+        stdout.write(`No issues found in organization '${org}'.\n`);
+        return;
+      }
+
+      writeListHeader(stdout, `Issues in ${org}`, false);
+      const termWidth = process.stdout.columns || 80;
+      const issuesWithOpts = response.data.map((issue) => ({
+        issue,
+        formatOptions: {
+          projectSlug: issue.project?.slug ?? "",
+          isMultiProject: false,
+        },
+      }));
+      writeIssueRows(stdout, issuesWithOpts, termWidth);
+
+      if (hasMore) {
+        const hint = `sentry issue list ${org}/ -c last`;
+        stdout.write(
+          `\nShowing ${response.data.length} issues (more available)\n`
+        );
+        stdout.write(`Next page: ${hint}\n`);
+      } else {
+        stdout.write(`\nShowing ${response.data.length} issues\n`);
+      }
+      return;
+    }
+
     // Resolve targets based on parsed argument type
     const { targets, footer, skippedSelfHosted, detectedDsns } =
       await resolveTargetsFromParsedArg(parsed, cwd);

src/commands/log/list.ts

@@ -8,17 +8,17 @@
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/bun";
 import type { SentryContext } from "../../context.js";
-import { findProjectsBySlug, listLogs } from "../../lib/api-client.js";
-import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
+import { listLogs } from "../../lib/api-client.js";
+import { validateLimit } from "../../lib/arg-parsing.js";
 import { buildCommand } from "../../lib/command.js";
-import { AuthError, ContextError } from "../../lib/errors.js";
+import { AuthError } from "../../lib/errors.js";
 import {
   formatLogRow,
   formatLogsHeader,
   writeFooter,
   writeJson,
 } from "../../lib/formatters/index.js";
-import { resolveOrgAndProject } from "../../lib/resolve-target.js";
+import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
 import { getUpdateNotification } from "../../lib/version-check.js";
 import type { SentryLog, Writer } from "../../types/index.js";
 
@@ -29,9 +29,6 @@ type ListFlags = {
   readonly json: boolean;
 };
 
-/** Usage hint for ContextError messages */
-const USAGE_HINT = "sentry log list <org>/<project>";
-
 /** Maximum allowed value for --limit flag */
 const MAX_LIMIT = 1000;
 
@@ -44,17 +41,14 @@ const DEFAULT_LIMIT = 100;
 /** Default poll interval in seconds for --follow mode */
 const DEFAULT_POLL_INTERVAL = 2;
 
+/** Command name used in resolver error messages */
+const COMMAND_NAME = "log list";
+
 /**
- * Validate that --limit value is within allowed range.
- *
- * @throws Error if value is outside MIN_LIMIT..MAX_LIMIT range
+ * Parse --limit flag, delegating range validation to shared utility.
  */
-function validateLimit(value: string): number {
-  const num = Number.parseInt(value, 10);
-  if (Number.isNaN(num) || num < MIN_LIMIT || num > MAX_LIMIT) {
-    throw new Error(`--limit must be between ${MIN_LIMIT} and ${MAX_LIMIT}`);
-  }
-  return num;
+function parseLimit(value: string): number {
+  return validateLimit(value, MIN_LIMIT, MAX_LIMIT);
 }
 
 /**
@@ -233,83 +227,6 @@ async function executeFollowMode(options: FollowModeOptions): Promise<void> {
   }
 }
 
-/** Resolved org and project for log commands */
-type ResolvedLogTarget = {
-  org: string;
-  project: string;
-};
-
-/**
- * Resolve org/project from parsed argument or auto-detection.
- *
- * Handles:
- * - explicit: "org/project" → use directly
- * - project-search: "project" → find project across all orgs
- * - auto-detect: no input → use DSN detection or config defaults
- *
- * @throws {ContextError} When target cannot be resolved
- */
-async function resolveLogTarget(
-  target: string | undefined,
-  cwd: string
-): Promise<ResolvedLogTarget> {
-  const parsed = parseOrgProjectArg(target);
-
-  switch (parsed.type) {
-    case "explicit":
-      return { org: parsed.org, project: parsed.project };
-
-    case "org-all":
-      throw new ContextError(
-        "Project",
-        `Please specify a project: sentry log list ${parsed.org}/<project>`
-      );
-
-    case "project-search": {
-      // Find project across all orgs
-      const matches = await findProjectsBySlug(parsed.projectSlug);
-
-      if (matches.length === 0) {
-        throw new ContextError(
-          "Project",
-          `No project '${parsed.projectSlug}' found in any accessible organization.\n\n` +
-            `Try: sentry log list <org>/${parsed.projectSlug}`
-        );
-      }
-
-      if (matches.length > 1) {
-        const options = matches
-          .map((m) => `  sentry log list ${m.orgSlug}/${m.slug}`)
-          .join("\n");
-        throw new ContextError(
-          "Project",
-          `Found '${parsed.projectSlug}' in ${matches.length} organizations. Please specify:\n${options}`
-        );
-      }
-
-      // Safe: we checked matches.length === 1 above, so first element exists
-      const match = matches[0] as (typeof matches)[number];
-      return { org: match.orgSlug, project: match.slug };
-    }
-
-    case "auto-detect": {
-      const resolved = await resolveOrgAndProject({
-        cwd,
-        usageHint: USAGE_HINT,
-      });
-      if (!resolved) {
-        throw new ContextError("Organization and project", USAGE_HINT);
-      }
-      return { org: resolved.org, project: resolved.project };
-    }
-
-    default: {
-      const _exhaustiveCheck: never = parsed;
-      throw new Error(`Unexpected parsed type: ${_exhaustiveCheck}`);
-    }
-  }
-}
-
 export const listCommand = buildCommand({
   docs: {
     brief: "List logs from a project",
@@ -341,7 +258,7 @@ export const listCommand = buildCommand({
     flags: {
       limit: {
         kind: "parsed",
-        parse: validateLimit,
+        parse: parseLimit,
         brief: `Number of log entries (${MIN_LIMIT}-${MAX_LIMIT})`,
         default: String(DEFAULT_LIMIT),
       },
@@ -378,7 +295,11 @@ export const listCommand = buildCommand({
     const { stdout, stderr, cwd, setContext } = this;
 
     // Resolve org/project from positional arg, config, or DSN auto-detection
-    const { org, project } = await resolveLogTarget(target, cwd);
+    const { org, project } = await resolveOrgProjectFromArg(
+      target,
+      cwd,
+      COMMAND_NAME
+    );
     setContext([org], [project]);
 
     if (flags.follow) {