feat: add pagination support to search command

Adds --all, --max-pages, and --cursor options to search command, enabling users to fetch all search results through automatic pagination. Follows the same pattern as bookmarks pagination for consistency.

src/commands/search.ts

@@ -9,13 +9,17 @@ export function registerSearchCommands(program: Command, ctx: CliContext): void
     .description('Search for tweets')
     .argument('<query>', 'Search query (e.g., "@clawdbot" or "from:clawdbot")')
     .option('-n, --count <number>', 'Number of tweets to fetch', '10')
+    .option('--all', 'Fetch all search results (paged)')
+    .option('--max-pages <number>', 'Stop after N pages when using --all')
+    .option('--cursor <string>', 'Resume pagination from a cursor')
     .option('--json', 'Output as JSON')
     .option('--json-full', 'Output as JSON with full raw API response in _raw field')
-    .action(async (query: string, cmdOpts: { count?: string; json?: boolean; jsonFull?: boolean }) => {
+    .action(async (query: string, cmdOpts: { count?: string; all?: boolean; maxPages?: string; cursor?: string; json?: boolean; jsonFull?: boolean }) => {
       const opts = program.opts();
       const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
       const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
       const count = Number.parseInt(cmdOpts.count || '10', 10);
+      const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
 
       const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
 
@@ -28,13 +32,33 @@ export function registerSearchCommands(program: Command, ctx: CliContext): void
         process.exit(1);
       }
 
+      const usePagination = cmdOpts.all || cmdOpts.cursor;
+      if (maxPages !== undefined && !usePagination) {
+        console.error(`${ctx.p('err')}--max-pages requires --all or --cursor.`);
+        process.exit(1);
+      }
+      if (!usePagination && (!Number.isFinite(count) || count <= 0)) {
+        console.error(`${ctx.p('err')}Invalid --count. Expected a positive integer.`);
+        process.exit(1);
+      }
+      if (maxPages !== undefined && (!Number.isFinite(maxPages) || maxPages <= 0)) {
+        console.error(`${ctx.p('err')}Invalid --max-pages. Expected a positive integer.`);
+        process.exit(1);
+      }
+
       const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
       const includeRaw = cmdOpts.jsonFull ?? false;
-      const result = await client.search(query, count, { includeRaw });
+      const searchOptions = { includeRaw };
+      const paginationOptions = { includeRaw, maxPages, cursor: cmdOpts.cursor };
+      const result = usePagination
+        ? await client.getAllSearchResults(query, paginationOptions)
+        : await client.search(query, count, searchOptions);
 
       if (result.success) {
-        ctx.printTweets(result.tweets, {
-          json: cmdOpts.json || cmdOpts.jsonFull,
+        const isJson = Boolean(cmdOpts.json || cmdOpts.jsonFull);
+        ctx.printTweetsResult(result, {
+          json: isJson,
+          usePagination: Boolean(usePagination),
           emptyMessage: 'No tweets found.',
         });
       } else {

src/lib/twitter-client-search.ts

@@ -12,8 +12,16 @@ export interface SearchFetchOptions {
   includeRaw?: boolean;
 }
 
+/** Options for paged search methods */
+export interface SearchPaginationOptions extends SearchFetchOptions {
+  maxPages?: number;
+  /** Starting cursor for pagination (resume from previous fetch) */
+  cursor?: string;
+}
+
 export interface TwitterClientSearchMethods {
   search(query: string, count?: number, options?: SearchFetchOptions): Promise<SearchResult>;
+  getAllSearchResults(query: string, options?: SearchPaginationOptions): Promise<SearchResult>;
 }
 
 function isQueryIdMismatch(payload: string): boolean {
@@ -50,12 +58,25 @@ export function withSearch<TBase extends AbstractConstructor<TwitterClientBase>>
      * Search for tweets matching a query
      */
     async search(query: string, count = 20, options: SearchFetchOptions = {}): Promise<SearchResult> {
-      const { includeRaw = false } = options;
+      return this.searchPaged(query, count, options);
+    }
+
+    /**
+     * Get all search results (paged)
+     */
+    async getAllSearchResults(query: string, options?: SearchPaginationOptions): Promise<SearchResult> {
+      return this.searchPaged(query, Number.POSITIVE_INFINITY, options);
+    }
+
+    private async searchPaged(query: string, limit: number, options: SearchPaginationOptions = {}): Promise<SearchResult> {
       const features = buildSearchFeatures();
       const pageSize = 20;
       const seen = new Set<string>();
       const tweets: TweetData[] = [];
-      let cursor: string | undefined;
+      let cursor: string | undefined = options.cursor;
+      let nextCursor: string | undefined;
+      let pagesFetched = 0;
+      const { includeRaw = false, maxPages } = options;
 
       const fetchPage = async (pageCount: number, pageCursor?: string) => {
         let lastError: string | undefined;
@@ -184,31 +205,42 @@ export function withSearch<TBase extends AbstractConstructor<TwitterClientBase>>
         return { success: false as const, error: firstAttempt.error };
       };
 
-      while (tweets.length < count) {
-        const pageCount = Math.min(pageSize, count - tweets.length);
+      const unlimited = !Number.isFinite(limit);
+      while (unlimited || tweets.length < limit) {
+        const pageCount = unlimited ? pageSize : Math.min(pageSize, limit - tweets.length);
         const page = await fetchWithRefresh(pageCount, cursor);
         if (!page.success) {
           return { success: false, error: page.error };
         }
+        pagesFetched += 1;
 
+        let added = 0;
         for (const tweet of page.tweets) {
           if (seen.has(tweet.id)) {
             continue;
           }
           seen.add(tweet.id);
           tweets.push(tweet);
-          if (tweets.length >= count) {
+          added += 1;
+          if (!unlimited && tweets.length >= limit) {
             break;
           }
         }
 
-        if (!page.cursor || page.cursor === cursor || page.tweets.length === 0) {
+        const pageCursor = page.cursor;
+        if (!pageCursor || pageCursor === cursor || page.tweets.length === 0 || added === 0) {
+          nextCursor = undefined;
           break;
         }
-        cursor = page.cursor;
+        if (maxPages && pagesFetched >= maxPages) {
+          nextCursor = pageCursor;
+          break;
+        }
+        cursor = pageCursor;
+        nextCursor = pageCursor;
       }
 
-      return { success: true, tweets };
+      return { success: true, tweets, nextCursor };
     }
   }