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

@@ -8,10 +8,12 @@
 import type { SentryContext } from "../../context.js";
 import { buildOrgAwareAliases } from "../../lib/alias.js";
 import {
+  API_MAX_PER_PAGE,
   findProjectsBySlug,
-  listIssues,
+  listIssuesAllPages,
   listIssuesPaginated,
   listProjects,
+  MAX_PAGINATION_PAGES,
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
 import { buildCommand } from "../../lib/command.js";
@@ -26,7 +28,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 +83,12 @@ 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).
+ * Derived from the page safety bound × the API's per-page cap.
+ */
+const MAX_LIMIT = MAX_PAGINATION_PAGES * API_MAX_PER_PAGE;
+
 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,44 @@ 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> {
+  // When resuming with --cursor, fetch a single page so the cursor chain stays intact.
+  if (cursor) {
+    const perPage = Math.min(flags.limit, API_MAX_PER_PAGE);
+    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 via the shared helper.
+  const { issues, nextCursor } = await listIssuesAllPages(org, "", {
+    query: flags.query,
+    limit: flags.limit,
+    sort: flags.sort,
+  });
+  return { issues, nextCursor };
+}
+
 /** Options for {@link handleOrgAllIssues}. */
 type OrgAllIssuesOptions = {
   stdout: Writer;
@@ -431,30 +486,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 +519,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 +529,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 +714,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 +728,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 +756,20 @@ 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 < 1) {
+      throw new ValidationError("--limit must be at least 1.", "limit");
+    }
+    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

@@ -9,7 +9,6 @@
  */
 
 import {
-  listAnOrganization_sIssues,
   listAnOrganization_sTeams,
   listAProject_sClientKeys,
   listAProject_sTeams,
@@ -198,15 +197,21 @@ function extractLinkAttr(segment: string, attr: string): string | undefined {
  * Maximum number of pages to follow when auto-paginating.
  *
  * Safety limit to prevent runaway pagination when the API returns an unexpectedly
- * large number of pages. At 100 items/page this allows up to 5,000 items, which
+ * large number of pages. At API_MAX_PER_PAGE items/page this allows up to 5,000 items, which
  * covers even the largest organizations. Override with SENTRY_MAX_PAGINATION_PAGES
  * env var for edge cases.
  */
-const MAX_PAGINATION_PAGES = Math.max(
+export const MAX_PAGINATION_PAGES = Math.max(
   1,
   Number(process.env.SENTRY_MAX_PAGINATION_PAGES) || 50
 );
 
+/**
+ * Sentry API's maximum items per page.
+ * Requests for more items are silently capped server-side.
+ */
+export const API_MAX_PER_PAGE = 100;
+
 /**
  * Paginated API response with cursor metadata.
  * More pages exist when `nextCursor` is defined.
@@ -512,13 +517,13 @@ async function orgScopedRequestPaginated<T>(
  *
  * @param endpoint - API endpoint path containing the org slug
  * @param options - Request options (schema must validate an array type)
- * @param perPage - Number of items per API page (default: 100)
+ * @param perPage - Number of items per API page (default: API_MAX_PER_PAGE)
  * @returns Combined array of all results across all pages
  */
 async function orgScopedPaginateAll<T>(
   endpoint: string,
   options: ApiRequestOptions<T[]>,
-  perPage = 100
+  perPage = API_MAX_PER_PAGE
 ): Promise<T[]> {
   const allResults: T[] = [];
   let cursor: string | undefined;
@@ -655,7 +660,7 @@ export function listProjectsPaginated(
     `/organizations/${orgSlug}/projects/`,
     {
       params: {
-        per_page: options.perPage ?? 100,
+        per_page: options.perPage ?? API_MAX_PER_PAGE,
         cursor: options.cursor,
       },
     }
@@ -982,44 +987,6 @@ export async function getProjectKeys(
 
 // Issue functions
 
-/**
- * List issues for a project.
- * Uses the org-scoped endpoint (the project-scoped one is deprecated).
- * Uses region-aware routing for multi-region support.
- */
-export async function listIssues(
-  orgSlug: string,
-  projectSlug: string,
-  options: {
-    query?: string;
-    cursor?: string;
-    limit?: number;
-    sort?: "date" | "new" | "freq" | "user";
-    statsPeriod?: string;
-  } = {}
-): Promise<SentryIssue[]> {
-  const config = await getOrgSdkConfig(orgSlug);
-
-  // Build query with project filter: "project:{slug}" prefix
-  const projectFilter = `project:${projectSlug}`;
-  const fullQuery = [projectFilter, options.query].filter(Boolean).join(" ");
-
-  const result = await listAnOrganization_sIssues({
-    ...config,
-    path: { organization_id_or_slug: orgSlug },
-    query: {
-      query: fullQuery,
-      cursor: options.cursor,
-      limit: options.limit,
-      sort: options.sort,
-      statsPeriod: options.statsPeriod,
-    },
-  });
-
-  const data = unwrapResult(result, "Failed to list issues");
-  return data as unknown as SentryIssue[];
-}
-
 /**
  * List issues for a project with pagination control.
  * Returns a single page of results with cursor metadata for manual pagination.
@@ -1064,6 +1031,75 @@ export function listIssuesPaginated(
   );
 }
 
+/** Result from {@link listIssuesAllPages}. */
+export type IssuesPage = {
+  issues: SentryIssue[];
+  /**
+   * Cursor for the next page of results, if more exist beyond the returned
+   * issues. `undefined` when all matching issues have been returned OR when
+   * the last page was trimmed to fit `limit` (cursor would skip items).
+   */
+  nextCursor?: string;
+};
+
+/**
+ * Auto-paginate through issues up to the requested limit.
+ *
+ * The Sentry API caps `per_page` at {@link API_MAX_PER_PAGE} server-side. When the caller
+ * requests more than that, 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 Issues (up to `limit` items) and a cursor for the next page if available
+ */
+export async function listIssuesAllPages(
+  orgSlug: string,
+  projectSlug: string,
+  options: {
+    query?: string;
+    limit: number;
+    sort?: "date" | "new" | "freq" | "user";
+    statsPeriod?: string;
+  }
+): Promise<IssuesPage> {
+  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, API_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) {
+      // If we overshot the limit, trim and don't return a nextCursor —
+      // the cursor would point past the trimmed items, causing skips.
+      if (allResults.length > options.limit) {
+        return { issues: allResults.slice(0, options.limit) };
+      }
+      return { issues: allResults, nextCursor: response.nextCursor };
+    }
+
+    cursor = response.nextCursor;
+  }
+
+  // Safety limit reached — return what we have, no nextCursor
+  return { issues: allResults.slice(0, options.limit) };
+}
+
 /**
  * Get a specific issue by numeric ID.
  */
@@ -1443,7 +1479,7 @@ export async function listLogs(
       field: LOG_FIELDS,
       project: isNumericProject ? [Number(projectSlug)] : undefined,
       query: fullQuery || undefined,
-      per_page: options.limit || 100,
+      per_page: options.limit || API_MAX_PER_PAGE,
       statsPeriod: options.statsPeriod ?? "7d",
       sort: "-timestamp",
     },