fix(issue-list): auto-paginate --limit beyond 100 (#268)

When users passed --limit > 100, the Sentry API silently capped results
at 100. The CLI now transparently fetches multiple pages to satisfy the
requested limit.

- Add listIssuesAllPages() in api-client.ts: cursor-paginates up to the
  requested limit using listIssuesPaginated, bounded by MAX_PAGINATION_PAGES
- Switch fetchIssuesForTarget to use listIssuesAllPages instead of listIssues
- Cap --limit at 1000 (non-org-all) and 100 (org-all page size) with a
  clear ValidationError pointing to cursor pagination for larger sets
- Change default --limit from 10 to 25
- Update help text to document auto-pagination semantics

Author: BYK

src/commands/issue/list.ts

@@ -9,7 +9,7 @@ import type { SentryContext } from "../../context.js";
 import { buildOrgAwareAliases } from "../../lib/alias.js";
 import {
   findProjectsBySlug,
-  listIssues,
+  listIssuesAllPages,
   listIssuesPaginated,
   listProjects,
 } from "../../lib/api-client.js";
@@ -26,7 +26,12 @@ import {
   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,
@@ -76,6 +81,15 @@ const VALID_SORT_VALUES: SortValue[] = ["date", "new", "freq", "user"];
 /** Usage hint for ContextError messages */
 const USAGE_HINT = "sentry issue list <org>/<project>";
 
+/** Maximum --limit value for non-org-all modes (auto-pagination ceiling). */
+const MAX_LIMIT = 1000;
+
+/**
+ * Sentry API's max per_page for issues. In org-all mode --limit controls page
+ * size, so it's capped here to avoid the API silently clamping it.
+ */
+const API_MAX_PER_PAGE = 100;
+
 function parseSort(value: string): SortValue {
   if (!VALID_SORT_VALUES.includes(value as SortValue)) {
     throw new Error(
@@ -378,7 +392,11 @@ async function fetchIssuesForTarget(
   options: { query?: string; limit: number; sort: SortValue }
 ): Promise<FetchResult> {
   try {
-    const issues = await listIssues(target.org, target.project, options);
+    const issues = await listIssuesAllPages(
+      target.org,
+      target.project,
+      options
+    );
     return { success: true, data: { target, issues } };
   } catch (error) {
     // Auth errors should propagate - user needs to authenticate
@@ -664,7 +682,11 @@ export const listCommand = buildCommand({
       "  sentry issue list <org>/        # all projects in org (trailing / required)\n" +
       "  sentry issue list <project>     # find project across all orgs\n\n" +
       `${targetPatternExplanation()}\n\n` +
-      "In monorepos with multiple Sentry projects, shows issues from all detected projects.",
+      "In monorepos with multiple Sentry projects, shows issues from all detected projects.\n\n" +
+      "The --limit flag specifies the total number of results to fetch (max 1000). " +
+      "When the limit exceeds the API page size (100), multiple requests are made " +
+      "automatically. In <org>/ mode, --limit controls the page size for cursor " +
+      "pagination (max 100).",
   },
   parameters: {
     positional: LIST_TARGET_POSITIONAL,
@@ -675,7 +697,7 @@ export const listCommand = buildCommand({
         brief: "Search query (Sentry search syntax)",
         optional: true,
       },
-      limit: buildListLimitFlag("issues", "10"),
+      limit: buildListLimitFlag("issues", "25"),
       sort: {
         kind: "parsed",
         parse: parseSort,
@@ -703,6 +725,24 @@ export const listCommand = buildCommand({
 
     const parsed = parseOrgProjectArg(target);
 
+    // Validate --limit range based on mode.
+    // org-all: --limit is page size, cap at API max (100).
+    // Others: --limit is total results, cap at MAX_LIMIT (1000).
+    if (parsed.type === "org-all") {
+      if (flags.limit > API_MAX_PER_PAGE) {
+        throw new ValidationError(
+          `--limit cannot exceed ${API_MAX_PER_PAGE} in <org>/ mode (page size for cursor pagination).`,
+          "limit"
+        );
+      }
+    } else if (flags.limit > MAX_LIMIT) {
+      throw new ValidationError(
+        `--limit cannot exceed ${MAX_LIMIT}. ` +
+          "Use 'sentry issue list <org>/' with --cursor for larger result sets.",
+        "limit"
+      );
+    }
+
     // biome-ignore lint/suspicious/noExplicitAny: shared handler accepts any mode variant
     const resolveAndHandle: ModeHandler<any> = (ctx) =>
       handleResolvedTargets({ ...ctx, flags, stderr, setContext });

src/lib/api-client.ts

@@ -1064,6 +1064,65 @@ export function listIssuesPaginated(
   );
 }
 
+/**
+ * Sentry API's maximum items per page for the issues endpoint.
+ * Requests above this are silently capped server-side.
+ */
+const ISSUES_MAX_PER_PAGE = 100;
+
+/**
+ * Auto-paginate through issues up to the requested limit.
+ *
+ * The Sentry issues API caps `per_page` at 100 server-side. When the caller
+ * requests more than 100 issues, this function transparently fetches multiple
+ * pages using cursor-based pagination and returns the combined result.
+ *
+ * Safety-bounded by {@link MAX_PAGINATION_PAGES} to prevent runaway requests.
+ *
+ * @param orgSlug - Organization slug
+ * @param projectSlug - Project slug (empty string for org-wide)
+ * @param options - Query, sort, and limit options
+ * @returns Combined array of issues (up to `limit` items)
+ */
+export async function listIssuesAllPages(
+  orgSlug: string,
+  projectSlug: string,
+  options: {
+    query?: string;
+    limit: number;
+    sort?: "date" | "new" | "freq" | "user";
+    statsPeriod?: string;
+  }
+): Promise<SentryIssue[]> {
+  const allResults: SentryIssue[] = [];
+  let cursor: string | undefined;
+
+  // Use the smaller of the requested limit and the API max as page size
+  const perPage = Math.min(options.limit, ISSUES_MAX_PER_PAGE);
+
+  for (let page = 0; page < MAX_PAGINATION_PAGES; page++) {
+    const response = await listIssuesPaginated(orgSlug, projectSlug, {
+      query: options.query,
+      cursor,
+      perPage,
+      sort: options.sort,
+      statsPeriod: options.statsPeriod,
+    });
+
+    allResults.push(...response.data);
+
+    // Stop if we've reached the requested limit or there are no more pages
+    if (allResults.length >= options.limit || !response.nextCursor) {
+      break;
+    }
+
+    cursor = response.nextCursor;
+  }
+
+  // Trim to exact limit (last page may overshoot)
+  return allResults.slice(0, options.limit);
+}
+
 /**
  * Get a specific issue by numeric ID.
  */