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,8 @@ import type { SentryContext } from "../../context.js";
 import { buildOrgAwareAliases } from "../../lib/alias.js";
 import {
   findProjectsBySlug,
-  listIssues,
+  ISSUES_MAX_PER_PAGE,
+  listIssuesAllPages,
   listIssuesPaginated,
   listProjects,
 } from "../../lib/api-client.js";
@@ -26,7 +27,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 +82,13 @@ 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 (auto-pagination ceiling).
+ * Equals MAX_PAGINATION_PAGES * ISSUES_MAX_PER_PAGE — the theoretical maximum
+ * the auto-paginator can return. Kept lower for practical CLI response times.
+ */
+const MAX_LIMIT = 1000;
+
 function parseSort(value: string): SortValue {
   if (!VALID_SORT_VALUES.includes(value as SortValue)) {
     throw new Error(
@@ -378,7 +391,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
@@ -406,6 +423,67 @@ function nextPageHint(org: string, flags: ListFlags): string {
   return parts.length > 0 ? `${base} ${parts.join(" ")}` : base;
 }
 
+/** Result from fetching org-wide issues (with or without cursor). */
+type OrgAllFetchResult = {
+  issues: SentryIssue[];
+  nextCursor?: string;
+};
+
+/**
+ * Fetch org-wide issues, auto-paginating from the start or resuming from a cursor.
+ *
+ * When `cursor` is provided (--cursor resume), fetches a single page to keep the
+ * cursor chain intact. Otherwise auto-paginates up to the requested limit.
+ */
+async function fetchOrgAllIssues(
+  org: string,
+  flags: Pick<ListFlags, "query" | "limit" | "sort">,
+  cursor: string | undefined
+): Promise<OrgAllFetchResult> {
+  const perPage = Math.min(flags.limit, ISSUES_MAX_PER_PAGE);
+
+  // When resuming with --cursor, fetch a single page so the cursor chain stays intact.
+  if (cursor) {
+    const response = await listIssuesPaginated(org, "", {
+      query: flags.query,
+      cursor,
+      perPage,
+      sort: flags.sort,
+    });
+    return { issues: response.data, nextCursor: response.nextCursor };
+  }
+
+  // No cursor — auto-paginate from the beginning.
+  const issues: SentryIssue[] = [];
+  let pageCursor: string | undefined;
+  let lastCursor: string | undefined;
+
+  // Safety-bounded at 50 pages to match the auto-paginator in api-client.ts.
+  const MAX_PAGES = 50;
+  for (let page = 0; issues.length < flags.limit && page < MAX_PAGES; page++) {
+    const response = await listIssuesPaginated(org, "", {
+      query: flags.query,
+      cursor: pageCursor,
+      perPage,
+      sort: flags.sort,
+    });
+
+    issues.push(...response.data);
+    lastCursor = response.nextCursor;
+
+    if (!response.nextCursor) {
+      break;
+    }
+    pageCursor = response.nextCursor;
+  }
+
+  // Trim to exact limit (last page may overshoot)
+  return {
+    issues: issues.length > flags.limit ? issues.slice(0, flags.limit) : issues,
+    nextCursor: lastCursor,
+  };
+}
+
 /** Options for {@link handleOrgAllIssues}. */
 type OrgAllIssuesOptions = {
   stdout: Writer;
@@ -431,30 +509,25 @@ async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
 
   setContext([org], []);
 
-  const response = await listIssuesPaginated(org, "", {
-    query: flags.query,
-    cursor,
-    perPage: flags.limit,
-    sort: flags.sort,
-  });
+  const { issues, nextCursor } = await fetchOrgAllIssues(org, flags, cursor);
 
-  if (response.nextCursor) {
-    setPaginationCursor(PAGINATION_KEY, contextKey, response.nextCursor);
+  if (nextCursor) {
+    setPaginationCursor(PAGINATION_KEY, contextKey, nextCursor);
   } else {
     clearPaginationCursor(PAGINATION_KEY, contextKey);
   }
 
-  const hasMore = !!response.nextCursor;
+  const hasMore = !!nextCursor;
 
   if (flags.json) {
     const output = hasMore
-      ? { data: response.data, nextCursor: response.nextCursor, hasMore: true }
-      : { data: response.data, hasMore: false };
+      ? { data: issues, nextCursor, hasMore: true }
+      : { data: issues, hasMore: false };
     writeJson(stdout, output);
     return;
   }
 
-  if (response.data.length === 0) {
+  if (issues.length === 0) {
     if (hasMore) {
       stdout.write(
         `No issues on this page. Try the next page: ${nextPageHint(org, flags)}\n`
@@ -469,7 +542,7 @@ async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
   // column is needed to identify which project each issue belongs to.
   writeListHeader(stdout, `Issues in ${org}`, true);
   const termWidth = process.stdout.columns || 80;
-  const issuesWithOpts = response.data.map((issue) => ({
+  const issuesWithOpts = issues.map((issue) => ({
     issue,
     formatOptions: {
       projectSlug: issue.project?.slug ?? "",
@@ -479,10 +552,10 @@ async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
   writeIssueRows(stdout, issuesWithOpts, termWidth);
 
   if (hasMore) {
-    stdout.write(`\nShowing ${response.data.length} issues (more available)\n`);
+    stdout.write(`\nShowing ${issues.length} issues (more available)\n`);
     stdout.write(`Next page: ${nextPageHint(org, flags)}\n`);
   } else {
-    stdout.write(`\nShowing ${response.data.length} issues\n`);
+    stdout.write(`\nShowing ${issues.length} issues\n`);
   }
 }
 
@@ -664,7 +737,10 @@ 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. Use --cursor to paginate through larger result sets.",
   },
   parameters: {
     positional: LIST_TARGET_POSITIONAL,
@@ -675,7 +751,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 +779,17 @@ export const listCommand = buildCommand({
 
     const parsed = parseOrgProjectArg(target);
 
+    // Validate --limit range. Auto-pagination handles the API's 100-per-page
+    // cap transparently, but we cap the total at MAX_LIMIT for practical CLI
+    // response times. Use --cursor for paginating through larger result sets.
+    if (flags.limit > MAX_LIMIT) {
+      throw new ValidationError(
+        `--limit cannot exceed ${MAX_LIMIT}. ` +
+          "Use --cursor to paginate through 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.
+ */
+export 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.
  */