fix(paginate): bound cursor loops without dropping empty pages (#48)

* fix(paginate): break loop on empty items with non-null nextToken

paginate() in pagination.ts entered an infinite loop when the API
returned { items: [], nextToken: 'cursor' }. The loop only checked
nextToken !== null, never whether items was empty. Any filtered list
command returning zero results would hang indefinitely.

Add an early-exit guard: if the page contains zero items, break
regardless of nextToken. Includes 5 unit tests covering the bug
reproduction, maxItems cap, single-page, and consecutive empty pages.

Closes #35

Signed-off-by: Aldo Rizona <aldorizona10@gmail.com>

* style(test): reflow pagination.test.ts to satisfy prettier format:check gate

Pure mechanical prettier reflow of two vi.fn(async () => ({...})) callbacks in
test/pagination.test.ts. No logic change — only line wrapping to satisfy the
format:check CI gate (npm run format:check). All other gates already pass.
Coverage remains >=80% on all 4 metrics (lines/statements/functions/branches).

* fix(paginate): bound cursor loops without dropping empty pages

---------

Signed-off-by: Aldo Rizona <aldorizona10@gmail.com>

Author: aldorizona10-glitch

src/lib/pagination.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import { ApiError } from './errors.js';
-import { paginate, validatePaginationFlags, type FetchPage, type Page } from './pagination.js';
+import {
+  MAX_AUTO_PAGES,
+  paginate,
+  validatePaginationFlags,
+  type FetchPage,
+  type Page,
+} from './pagination.js';
 
 function makePages<T>(pages: Page<T>[]): {
   fetchPage: FetchPage<T>;
@@ -121,4 +127,55 @@ describe('paginate', () => {
     await expect(paginate(fetchPage, { pageSize: 0 })).rejects.toBeInstanceOf(ApiError);
     expect(calls).toHaveLength(0);
   });
+
+  it('continues through empty cursor pages until later data', async () => {
+    const { fetchPage, calls } = makePages([
+      { items: [], nextToken: 'cursor-1' },
+      { items: [1], nextToken: null },
+    ]);
+
+    const page = await paginate(fetchPage);
+
+    expect(page.items).toEqual([1]);
+    expect(page.nextToken).toBeNull();
+    expect(calls).toHaveLength(2);
+    expect(calls[1]!.cursor).toBe('cursor-1');
+  });
+
+  it('rejects when API repeats a non-null cursor without making progress', async () => {
+    const { fetchPage, calls } = makePages([{ items: [], nextToken: 'cursor-1' }]);
+
+    await expect(paginate(fetchPage)).rejects.toMatchObject({
+      code: 'UNAVAILABLE',
+      details: expect.objectContaining({ reason: 'repeated_next_token' }),
+    });
+
+    expect(calls).toHaveLength(2);
+  });
+
+  it('rejects when auto-pagination exceeds the page safety cap', async () => {
+    const calls: Array<{ pageSize: number; cursor: string | undefined }> = [];
+    const fetchPage: FetchPage<number> = async args => {
+      calls.push(args);
+      return {
+        items: [],
+        nextToken:
+          args.cursor === undefined ? 'cursor-1' : `cursor-${Number(args.cursor.slice(7)) + 1}`,
+      };
+    };
+
+    let thrown: unknown;
+    try {
+      await paginate(fetchPage);
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(ApiError);
+    expect(thrown).toMatchObject({
+      code: 'UNAVAILABLE',
+      details: expect.objectContaining({ reason: 'max_pages_exceeded' }),
+    });
+    expect(calls).toHaveLength(MAX_AUTO_PAGES);
+  });
 });

src/lib/pagination.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from './http.js';
-import { localValidationError } from './errors.js';
+import { ApiError, localValidationError } from './errors.js';
 
 /**
  * Page shape returned by every list endpoint per
@@ -22,6 +22,7 @@ export interface PaginationFlags {
 
 const HARD_PAGE_SIZE_CAP = 100;
 const DEFAULT_PAGE_SIZE = 25;
+export const MAX_AUTO_PAGES = 1000;
 
 /**
  * Validates and normalizes pagination flags. Per the CLI OpenAPI spec
@@ -91,14 +92,24 @@ export async function paginate<T>(
   const items: T[] = [];
   let cursor: string | undefined = flags.startingToken;
   let lastNextToken: string | null = null;
+  let pagesFetched = 0;
+  const seenNextTokens = new Set<string>();
+  if (cursor !== undefined) seenNextTokens.add(cursor);
 
   while (true) {
     const remaining = maxItems !== undefined ? maxItems - items.length : Infinity;
     if (remaining <= 0) break;
+    if (pagesFetched >= MAX_AUTO_PAGES) {
+      throw paginationSafetyError('max_pages_exceeded', {
+        maxPages: MAX_AUTO_PAGES,
+        lastCursor: cursor ?? null,
+      });
+    }
 
     const callPageSize = Number.isFinite(remaining) ? Math.min(pageSize, remaining) : pageSize;
 
     const page = await fetchPage({ pageSize: callPageSize, cursor });
+    pagesFetched += 1;
     lastNextToken = page.nextToken;
 
     for (const item of page.items) {
@@ -107,12 +118,30 @@ export async function paginate<T>(
     }
 
     if (page.nextToken === null) break;
+    if (seenNextTokens.has(page.nextToken)) {
+      throw paginationSafetyError('repeated_next_token', {
+        cursor: page.nextToken,
+        pagesFetched,
+      });
+    }
+    seenNextTokens.add(page.nextToken);
     cursor = page.nextToken;
   }
 
   return { items, nextToken: lastNextToken };
 }
 
+function paginationSafetyError(reason: string, details: Record<string, unknown>): ApiError {
+  return ApiError.fromEnvelope({
+    code: 'UNAVAILABLE',
+    message: 'Pagination did not make progress safely.',
+    nextAction:
+      'Retry later. If the problem continues, contact TestSprite support with the cursor details.',
+    requestId: 'local',
+    details: { reason, ...details },
+  });
+}
+
 /**
  * Drop-in helper for commands that take a single page and surface
  * the cursor verbatim (no auto-follow). Used when the caller passed