@jackwener/opencli 1.3.3 → 1.4.1

package/dist/clis/twitter/profile.js

@@ -1,3 +1,4 @@
+import { AuthRequiredError, CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'twitter',
@@ -21,7 +22,7 @@ cli({
         return link ? link.getAttribute('href') : null;
       }`);
             if (!href)
-                throw new Error('Could not detect logged-in user. Are you logged in?');
+                throw new AuthRequiredError('x.com', 'Could not detect logged-in user. Are you logged in?');
             username = href.replace('/', '');
         }
         // Navigate directly to the user's profile page (gives us cookie context)
@@ -117,7 +118,9 @@ cli({
       }
     `);
         if (result?.error) {
-            throw new Error(result.error + (result.hint ? ` (${result.hint})` : ''));
+            if (String(result.error).includes('No ct0 cookie'))
+                throw new AuthRequiredError('x.com', result.error);
+            throw new CommandExecutionError(result.error + (result.hint ? ` (${result.hint})` : ''));
         }
         return result || [];
     }

package/dist/clis/twitter/reply-dm.js

@@ -1,3 +1,4 @@
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'twitter',
@@ -15,7 +16,7 @@ cli({
     columns: ['index', 'status', 'user', 'message'],
     func: async (page, kwargs) => {
         if (!page)
-            throw new Error('Requires browser');
+            throw new CommandExecutionError('Browser session required for twitter reply-dm');
         const messageText = kwargs.text;
         const maxSend = kwargs.max ?? 20;
         const skipReplied = kwargs['skip-replied'] !== false;

package/dist/clis/twitter/reply.js

@@ -1,3 +1,4 @@
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'twitter',
@@ -13,7 +14,7 @@ cli({
     columns: ['status', 'message', 'text'],
     func: async (page, kwargs) => {
         if (!page)
-            throw new Error('Requires browser');
+            throw new CommandExecutionError('Browser session required for twitter reply');
         // 1. Navigate to the tweet page
         await page.goto(kwargs.url);
         await page.wait(5); // Wait for the react application to hydrate

package/dist/clis/twitter/search.js

@@ -1,4 +1,33 @@
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
+/**
+ * Trigger Twitter search SPA navigation and retry once on transient failures.
+ *
+ * Twitter/X sometimes keeps the page on /explore for a short period even after
+ * pushState + popstate. A second attempt is enough for the intermittent cases
+ * reported in issue #353 while keeping the flow narrowly scoped.
+ */
+async function navigateToSearch(page, query, filter) {
+    const searchUrl = JSON.stringify(`/search?q=${encodeURIComponent(query)}&f=${filter}`);
+    let lastPath = '';
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        await page.evaluate(`
+      (() => {
+        window.history.pushState({}, '', ${searchUrl});
+        window.dispatchEvent(new PopStateEvent('popstate', { state: {} }));
+      })()
+    `);
+        await page.wait(5);
+        lastPath = String(await page.evaluate('() => window.location.pathname') || '');
+        if (lastPath.startsWith('/search')) {
+            return;
+        }
+        if (attempt < 2) {
+            await page.wait(1);
+        }
+    }
+    throw new CommandExecutionError(`SPA navigation to /search failed. Final path: ${lastPath || '(empty)'}. Twitter may have changed its routing.`);
+}
 cli({
     site: 'twitter',
     name: 'search',
@@ -8,11 +37,13 @@ cli({
     browser: true,
     args: [
         { name: 'query', type: 'string', required: true, positional: true },
+        { name: 'filter', type: 'string', default: 'top', choices: ['top', 'live'] },
         { name: 'limit', type: 'int', default: 15 },
     ],
     columns: ['id', 'author', 'text', 'likes', 'views', 'url'],
     func: async (page, kwargs) => {
         const query = kwargs.query;
+        const filter = kwargs.filter === 'live' ? 'live' : 'top';
         // 1. Navigate to x.com/explore (has a search input at the top)
         await page.goto('https://x.com/explore');
         await page.wait(3);
@@ -25,19 +56,7 @@ cli({
         //    a full page reload, so the interceptor stays alive.
         //    Note: the previous approach (nativeSetter + Enter keydown on the
         //    search input) does not reliably trigger Twitter's form submission.
-        const searchUrl = JSON.stringify(`/search?q=${encodeURIComponent(query)}&f=top`);
-        await page.evaluate(`
-      (() => {
-        window.history.pushState({}, '', ${searchUrl});
-        window.dispatchEvent(new PopStateEvent('popstate', { state: {} }));
-      })()
-    `);
-        await page.wait(5);
-        // Verify SPA navigation succeeded
-        const currentPath = await page.evaluate('() => window.location.pathname');
-        if (!currentPath?.startsWith('/search')) {
-            throw new Error('SPA navigation to /search failed. Twitter may have changed its routing.');
-        }
+        await navigateToSearch(page, query, filter);
         // 4. Scroll to trigger additional pagination
         await page.autoScroll({ times: 3, delayMs: 2000 });
         // 6. Retrieve captured data

package/dist/clis/twitter/search.test.d.ts

@@ -0,0 +1 @@
+import './search.js';

package/dist/clis/twitter/search.test.js

@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '../../registry.js';
+import './search.js';
+describe('twitter search command', () => {
+    it('retries transient SPA navigation failures before giving up', async () => {
+        const command = getRegistry().get('twitter/search');
+        expect(command?.func).toBeTypeOf('function');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/explore')
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            installInterceptor: vi.fn().mockResolvedValue(undefined),
+            evaluate,
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            getInterceptedRequests: vi.fn().mockResolvedValue([
+                {
+                    data: {
+                        search_by_raw_query: {
+                            search_timeline: {
+                                timeline: {
+                                    instructions: [
+                                        {
+                                            type: 'TimelineAddEntries',
+                                            entries: [
+                                                {
+                                                    entryId: 'tweet-1',
+                                                    content: {
+                                                        itemContent: {
+                                                            tweet_results: {
+                                                                result: {
+                                                                    rest_id: '1',
+                                                                    legacy: {
+                                                                        full_text: 'hello world',
+                                                                        favorite_count: 7,
+                                                                    },
+                                                                    core: {
+                                                                        user_results: {
+                                                                            result: {
+                                                                                core: {
+                                                                                    screen_name: 'alice',
+                                                                                },
+                                                                            },
+                                                                        },
+                                                                    },
+                                                                    views: {
+                                                                        count: '12',
+                                                                    },
+                                                                },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            ],
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                },
+            ]),
+        };
+        const result = await command.func(page, { query: 'from:alice', filter: 'top', limit: 5 });
+        expect(result).toEqual([
+            {
+                id: '1',
+                author: 'alice',
+                text: 'hello world',
+                likes: 7,
+                views: '12',
+                url: 'https://x.com/i/status/1',
+            },
+        ]);
+        expect(page.installInterceptor).toHaveBeenCalledWith('SearchTimeline');
+        expect(evaluate).toHaveBeenCalledTimes(4);
+    });
+    it('uses f=live in search URL when filter is live', async () => {
+        const command = getRegistry().get('twitter/search');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            installInterceptor: vi.fn().mockResolvedValue(undefined),
+            evaluate,
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            getInterceptedRequests: vi.fn().mockResolvedValue([]),
+        };
+        await command.func(page, { query: 'breaking news', filter: 'live', limit: 5 });
+        const pushStateCall = evaluate.mock.calls[0][0];
+        expect(pushStateCall).toContain('f=live');
+        expect(pushStateCall).toContain(encodeURIComponent('breaking news'));
+    });
+    it('uses f=top in search URL when filter is top', async () => {
+        const command = getRegistry().get('twitter/search');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            installInterceptor: vi.fn().mockResolvedValue(undefined),
+            evaluate,
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            getInterceptedRequests: vi.fn().mockResolvedValue([]),
+        };
+        await command.func(page, { query: 'test', filter: 'top', limit: 5 });
+        const pushStateCall = evaluate.mock.calls[0][0];
+        expect(pushStateCall).toContain('f=top');
+    });
+    it('falls back to top when filter is omitted', async () => {
+        const command = getRegistry().get('twitter/search');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            installInterceptor: vi.fn().mockResolvedValue(undefined),
+            evaluate,
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            getInterceptedRequests: vi.fn().mockResolvedValue([]),
+        };
+        await command.func(page, { query: 'test', limit: 5 });
+        const pushStateCall = evaluate.mock.calls[0][0];
+        expect(pushStateCall).toContain('f=top');
+    });
+    it('throws with the final path after both attempts fail', async () => {
+        const command = getRegistry().get('twitter/search');
+        expect(command?.func).toBeTypeOf('function');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/explore')
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce('/login');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            installInterceptor: vi.fn().mockResolvedValue(undefined),
+            evaluate,
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            getInterceptedRequests: vi.fn(),
+        };
+        await expect(command.func(page, { query: 'from:alice', filter: 'top', limit: 5 }))
+            .rejects
+            .toThrow('Final path: /login');
+        expect(page.autoScroll).not.toHaveBeenCalled();
+        expect(page.getInterceptedRequests).not.toHaveBeenCalled();
+        expect(evaluate).toHaveBeenCalledTimes(4);
+    });
+});

package/dist/clis/twitter/thread.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { AuthRequiredError } from '../../errors.js';
+import { AuthRequiredError, CommandExecutionError } from '../../errors.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
 const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const TWEET_DETAIL_QUERY_ID = 'nBS-WpgA6ZG0CyNHD517JQ';
@@ -136,7 +136,7 @@ cli({
       }`);
             if (data?.error) {
                 if (allTweets.length === 0)
-                    throw new Error(`HTTP ${data.error}: Tweet not found or queryId expired`);
+                    throw new CommandExecutionError(`HTTP ${data.error}: Tweet not found or queryId expired`);
                 break;
             }
             // TypeScript-side: type-safe parsing + cursor extraction

package/dist/clis/twitter/timeline.js

@@ -1,3 +1,4 @@
+import { AuthRequiredError, CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
 const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
@@ -159,7 +160,7 @@ cli({
       return document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1] || null;
     }`);
         if (!ct0)
-            throw new Error('Not logged into x.com (no ct0 cookie)');
+            throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         // Dynamically resolve queryId for the selected endpoint
         const resolved = await page.evaluate(`async () => {
       try {
@@ -195,7 +196,7 @@ cli({
       }`);
             if (data?.error) {
                 if (allTweets.length === 0)
-                    throw new Error(`HTTP ${data.error}: Failed to fetch timeline. queryId may have expired.`);
+                    throw new CommandExecutionError(`HTTP ${data.error}: Failed to fetch timeline. queryId may have expired.`);
                 break;
             }
             const { tweets, nextCursor } = parseHomeTimeline(data, seen);

package/dist/clis/twitter/trending.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { AuthRequiredError, EmptyResultError } from '../../errors.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
 const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 // ── CLI definition ────────────────────────────────────────────────────
@@ -23,7 +24,7 @@ cli({
       return document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1] || null;
     })()`);
         if (!ct0)
-            throw new Error('Not logged into x.com (no ct0 cookie)');
+            throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         // Try legacy guide.json API first (faster than DOM scraping)
         let trends = [];
         const apiData = await page.evaluate(`(async () => {
@@ -84,7 +85,7 @@ cli({
             }
         }
         if (trends.length === 0) {
-            throw new Error('No trending data found. API may have changed or login may be required.');
+            throw new EmptyResultError('twitter trending', 'API may have changed or login may be required.');
         }
         return trends.slice(0, limit);
     },

package/dist/clis/twitter/unblock.js

@@ -1,3 +1,4 @@
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'twitter',
@@ -12,7 +13,7 @@ cli({
     columns: ['status', 'message'],
     func: async (page, kwargs) => {
         if (!page)
-            throw new Error('Requires browser');
+            throw new CommandExecutionError('Browser session required for twitter unblock');
         const username = kwargs.username.replace(/^@/, '');
         await page.goto(`https://x.com/${username}`);
         await page.wait(5);

package/dist/clis/twitter/unbookmark.js

@@ -1,3 +1,4 @@
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'twitter',
@@ -12,7 +13,7 @@ cli({
     columns: ['status', 'message'],
     func: async (page, kwargs) => {
         if (!page)
-            throw new Error('Requires browser');
+            throw new CommandExecutionError('Browser session required for twitter unbookmark');
         await page.goto(kwargs.url);
         await page.wait(5);
         const result = await page.evaluate(`(async () => {

package/dist/clis/twitter/unfollow.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { CommandExecutionError } from '../../errors.js';
 cli({
     site: 'twitter',
     name: 'unfollow',
@@ -12,7 +13,7 @@ cli({
     columns: ['status', 'message'],
     func: async (page, kwargs) => {
         if (!page)
-            throw new Error('Requires browser');
+            throw new CommandExecutionError('Browser session required for twitter unfollow');
         const username = kwargs.username.replace(/^@/, '');
         await page.goto(`https://x.com/${username}`);
         await page.wait(5);

package/dist/clis/v2ex/daily.js

@@ -1,6 +1,7 @@
 /**
  * V2EX Daily Check-in adapter.
  */
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'v2ex',
@@ -13,7 +14,7 @@ cli({
     columns: ['status', 'message'],
     func: async (page) => {
         if (!page)
-            throw new Error('Browser page required');
+            throw new CommandExecutionError('Browser page required');
         if (process.env.OPENCLI_VERBOSE) {
             console.error('[opencli:v2ex] Navigating to /mission/daily');
         }
@@ -56,7 +57,7 @@ cli({
                 console.error(`[opencli:v2ex:debug] Page Title: ${checkResult.debug_title}`);
                 console.error(`[opencli:v2ex:debug] Page Body: ${checkResult.debug_body}`);
             }
-            throw new Error(checkResult.error);
+            throw new CommandExecutionError(checkResult.error);
         }
         if (checkResult.claimed) {
             return [{ status: '✅ 已签到', message: checkResult.message }];

package/dist/clis/v2ex/me.js

@@ -1,6 +1,7 @@
 /**
  * V2EX Me (Profile/Balance) adapter.
  */
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'v2ex',
@@ -13,7 +14,7 @@ cli({
     columns: ['username', 'balance', 'unread_notifications', 'daily_reward_ready'],
     func: async (page) => {
         if (!page)
-            throw new Error('Browser page required');
+            throw new CommandExecutionError('Browser page required');
         if (process.env.OPENCLI_VERBOSE) {
             console.error('[opencli:v2ex] Navigating to /');
         }
@@ -91,7 +92,7 @@ cli({
                 console.error(`[opencli:v2ex:debug] Page Title: ${data.debug_title}`);
                 console.error(`[opencli:v2ex:debug] Page Body: ${data.debug_body}`);
             }
-            throw new Error(data.error);
+            throw new CommandExecutionError(data.error);
         }
         return [data];
     },

package/dist/clis/v2ex/notifications.js

@@ -1,6 +1,7 @@
 /**
  * V2EX Notifications adapter.
  */
+import { CommandExecutionError } from '../../errors.js';
 import { cli, Strategy } from '../../registry.js';
 cli({
     site: 'v2ex',
@@ -15,7 +16,7 @@ cli({
     columns: ['type', 'content', 'time'],
     func: async (page, kwargs) => {
         if (!page)
-            throw new Error('Browser page required');
+            throw new CommandExecutionError('Browser page required');
         if (process.env.OPENCLI_VERBOSE) {
             console.error('[opencli:v2ex] Navigating to /notifications');
         }
@@ -62,9 +63,8 @@ cli({
         });
       }
     `);
-        if (!Array.isArray(data)) {
-            throw new Error('Failed to parse notifications data');
-        }
+        if (!Array.isArray(data))
+            throw new CommandExecutionError('Failed to parse notifications data');
         const limit = kwargs.limit || 20;
         return data.slice(0, limit);
     },

package/dist/clis/web/read.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generic web page reader — fetch any URL and export as Markdown.
+ *
+ * Uses browser-side DOM heuristics to extract the main content:
+ *   1. <article> element
+ *   2. [role="main"] element
+ *   3. <main> element
+ *   4. Largest text-dense block as fallback
+ *
+ * Pipes through the shared article-download pipeline (Turndown + image download).
+ *
+ * Usage:
+ *   opencli web read --url "https://www.anthropic.com/research/..." --output ./articles
+ *   opencli web read --url "https://..." --download-images false
+ */
+export {};