@jackwener/opencli 1.5.9 → 1.6.1

package/src/cli.ts

@@ -18,6 +18,13 @@ import { registerAllCommands } from './commanderAdapter.js';
 import { EXIT_CODES, getErrorMessage } from './errors.js';
 import { daemonStatus, daemonStop, daemonRestart } from './commands/daemon.js';
 
+/** Create a browser page for operate commands. Uses 'operate' workspace for session persistence. */
+async function getOperatePage(): Promise<import('./types.js').IPage> {
+  const { BrowserBridge } = await import('./browser/index.js');
+  const bridge = new BrowserBridge();
+  return bridge.connect({ timeout: 30, workspace: 'operate:default' });
+}
+
 export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
   const program = new Command();
   // enablePositionalOptions: prevents parent from consuming flags meant for subcommands;
@@ -229,6 +236,391 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       console.log(renderCascadeResult(result));
     });
 
+  // ── Built-in: operate (browser control for Claude Code skill) ───────────────
+  //
+  // Make websites accessible for AI agents.
+  // All commands wrapped in operateAction() for consistent error handling.
+
+  const operate = program
+    .command('operate')
+    .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+
+  /** Wrap operate actions with error handling and optional --json output */
+  function operateAction(fn: (page: Awaited<ReturnType<typeof getOperatePage>>, ...args: any[]) => Promise<unknown>) {
+    return async (...args: any[]) => {
+      try {
+        const page = await getOperatePage();
+        await fn(page, ...args);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Extension not connected') || msg.includes('Daemon')) {
+          console.error(`Browser not connected. Run 'opencli doctor' to diagnose.`);
+        } else if (msg.includes('attach failed') || msg.includes('chrome-extension://')) {
+          console.error(`Browser attach failed — another extension may be interfering. Try disabling 1Password.`);
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      }
+    };
+  }
+
+  // ── Navigation ──
+
+  /** Network interceptor JS — injected on every open/navigate to capture fetch/XHR */
+  const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=50000,F=window.fetch;window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();if(window.__opencli_net.length<M){var b=null;if(t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),method:(arguments[1]&&arguments[1].method)||'GET',status:r.status,size:t.length,ct:ct,body:b})}}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if((ct.includes('json')||ct.includes('text'))&&window.__opencli_net.length<M){var t=x.responseText,b=null;if(t&&t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:x._ou,method:x._om||'GET',status:x.status,size:t?t.length:0,ct:ct,body:b})}}catch(e){}});return S.apply(this,arguments)}})()`;
+
+  operate.command('open').argument('<url>').description('Open URL in automation window')
+    .action(operateAction(async (page, url) => {
+      await page.goto(url);
+      await page.wait(2);
+      // Auto-inject network interceptor for API discovery
+      try { await page.evaluate(NETWORK_INTERCEPTOR_JS); } catch { /* non-fatal */ }
+      console.log(`Navigated to: ${await page.getCurrentUrl?.() ?? url}`);
+    }));
+
+  operate.command('back').description('Go back in browser history')
+    .action(operateAction(async (page) => {
+      await page.evaluate('history.back()');
+      await page.wait(2);
+      console.log('Navigated back');
+    }));
+
+  operate.command('scroll').argument('<direction>', 'up or down').option('--amount <pixels>', 'Pixels to scroll', '500')
+    .description('Scroll page')
+    .action(operateAction(async (page, direction, opts) => {
+      if (direction !== 'up' && direction !== 'down') {
+        console.error(`Invalid direction "${direction}". Use "up" or "down".`);
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
+        return;
+      }
+      await page.scroll(direction, parseInt(opts.amount, 10));
+      console.log(`Scrolled ${direction}`);
+    }));
+
+  // ── Inspect ──
+
+  operate.command('state').description('Page state: URL, title, interactive elements with [N] indices')
+    .action(operateAction(async (page) => {
+      const snapshot = await page.snapshot({ viewportExpand: 800 });
+      const url = await page.getCurrentUrl?.() ?? '';
+      console.log(`URL: ${url}\n`);
+      console.log(typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2));
+    }));
+
+  operate.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)')
+    .description('Take screenshot')
+    .action(operateAction(async (page, path) => {
+      if (path) {
+        await page.screenshot({ path });
+        console.log(`Screenshot saved to: ${path}`);
+      } else {
+        console.log(await page.screenshot({ format: 'png' }));
+      }
+    }));
+
+  // ── Get commands (structured data extraction) ──
+
+  const get = operate.command('get').description('Get page properties');
+
+  get.command('title').description('Page title')
+    .action(operateAction(async (page) => {
+      console.log(await page.evaluate('document.title'));
+    }));
+
+  get.command('url').description('Current page URL')
+    .action(operateAction(async (page) => {
+      console.log(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
+    }));
+
+  get.command('text').argument('<index>', 'Element index').description('Element text content')
+    .action(operateAction(async (page, index) => {
+      const text = await page.evaluate(`document.querySelector('[data-opencli-ref="${index}"]')?.textContent?.trim()`);
+      console.log(text ?? '(empty)');
+    }));
+
+  get.command('value').argument('<index>', 'Element index').description('Input/textarea value')
+    .action(operateAction(async (page, index) => {
+      const val = await page.evaluate(`document.querySelector('[data-opencli-ref="${index}"]')?.value`);
+      console.log(val ?? '(empty)');
+    }));
+
+  get.command('html').option('--selector <css>', 'CSS selector scope').description('Page HTML (or scoped)')
+    .action(operateAction(async (page, opts) => {
+      const sel = opts.selector ? JSON.stringify(opts.selector) : 'null';
+      const html = await page.evaluate(`(${sel} ? document.querySelector(${sel})?.outerHTML : document.documentElement.outerHTML)?.slice(0, 50000)`);
+      console.log(html ?? '(empty)');
+    }));
+
+  get.command('attributes').argument('<index>', 'Element index').description('Element attributes')
+    .action(operateAction(async (page, index) => {
+      const attrs = await page.evaluate(`JSON.stringify(Object.fromEntries([...document.querySelector('[data-opencli-ref="${index}"]')?.attributes].map(a=>[a.name,a.value])))`);
+      console.log(attrs ?? '{}');
+    }));
+
+  // ── Interact ──
+
+  operate.command('click').argument('<index>', 'Element index from state').description('Click element by index')
+    .action(operateAction(async (page, index) => {
+      await page.click(index);
+      console.log(`Clicked element [${index}]`);
+    }));
+
+  operate.command('type').argument('<index>', 'Element index').argument('<text>', 'Text to type')
+    .description('Click element, then type text')
+    .action(operateAction(async (page, index, text) => {
+      await page.click(index);
+      await page.wait(0.3);
+      await page.typeText(index, text);
+      console.log(`Typed "${text}" into element [${index}]`);
+    }));
+
+  operate.command('select').argument('<index>', 'Element index of <select>').argument('<option>', 'Option text')
+    .description('Select dropdown option')
+    .action(operateAction(async (page, index, option) => {
+      const result = await page.evaluate(`
+        (function() {
+          var sel = document.querySelector('[data-opencli-ref="${index}"]');
+          if (!sel || sel.tagName !== 'SELECT') return { error: 'Not a <select>' };
+          var match = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
+          if (!match) return { error: 'Option not found', available: Array.from(sel.options).map(o => o.text.trim()) };
+          var setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+          if (setter) setter.call(sel, match.value); else sel.value = match.value;
+          sel.dispatchEvent(new Event('input', {bubbles:true}));
+          sel.dispatchEvent(new Event('change', {bubbles:true}));
+          return { selected: match.text };
+        })()
+      `) as { error?: string; selected?: string; available?: string[] } | null;
+      if (result?.error) {
+        console.error(`Error: ${result.error}${result.available ? ` — Available: ${result.available.join(', ')}` : ''}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      } else {
+        console.log(`Selected "${result?.selected}" in element [${index}]`);
+      }
+    }));
+
+  operate.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)')
+    .description('Press keyboard key')
+    .action(operateAction(async (page, key) => {
+      await page.pressKey(key);
+      console.log(`Pressed: ${key}`);
+    }));
+
+  // ── Wait commands ──
+
+  operate.command('wait')
+    .argument('<type>', 'selector, text, or time')
+    .argument('[value]', 'CSS selector, text string, or seconds')
+    .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
+    .description('Wait for selector, text, or time (e.g. wait selector ".loaded", wait text "Success", wait time 3)')
+    .action(operateAction(async (page, type, value, opts) => {
+      const timeout = parseInt(opts.timeout, 10);
+      if (type === 'time') {
+        const seconds = parseFloat(value ?? '2');
+        await page.wait(seconds);
+        console.log(`Waited ${seconds}s`);
+      } else if (type === 'selector') {
+        if (!value) { console.error('Missing CSS selector'); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        await page.wait({ selector: value, timeout: timeout / 1000 });
+        console.log(`Element "${value}" appeared`);
+      } else if (type === 'text') {
+        if (!value) { console.error('Missing text'); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        await page.wait({ text: value, timeout: timeout / 1000 });
+        console.log(`Text "${value}" appeared`);
+      } else {
+        console.error(`Unknown wait type "${type}". Use: selector, text, or time`);
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
+      }
+    }));
+
+  // ── Extract ──
+
+  operate.command('eval').argument('<js>', 'JavaScript code').description('Execute JS in page context, return result')
+    .action(operateAction(async (page, js) => {
+      const result = await page.evaluate(js);
+      if (typeof result === 'string') console.log(result);
+      else console.log(JSON.stringify(result, null, 2));
+    }));
+
+  // ── Network (API discovery) ──
+
+  operate.command('network')
+    .option('--detail <index>', 'Show full response body of request at index')
+    .option('--all', 'Show all requests including static resources')
+    .description('Show captured network requests (auto-captured since last open)')
+    .action(operateAction(async (page, opts) => {
+      const requests = await page.evaluate(`(function(){
+        var reqs = window.__opencli_net || [];
+        return JSON.stringify(reqs);
+      })()`) as string;
+
+      let items: Array<{ url: string; method: string; status: number; size: number; ct: string; body: unknown }> = [];
+      try { items = JSON.parse(requests); } catch { console.log('No network data captured. Run "operate open <url>" first.'); return; }
+
+      if (items.length === 0) { console.log('No requests captured.'); return; }
+
+      // Filter out static resources unless --all
+      if (!opts.all) {
+        items = items.filter(r =>
+          (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
+          !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
+          !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url)
+        );
+      }
+
+      if (opts.detail !== undefined) {
+        const idx = parseInt(opts.detail, 10);
+        const req = items[idx];
+        if (!req) { console.error(`Request #${idx} not found. ${items.length} requests available.`); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        console.log(`${req.method} ${req.url}`);
+        console.log(`Status: ${req.status} | Size: ${req.size} | Type: ${req.ct}`);
+        console.log('---');
+        console.log(typeof req.body === 'string' ? req.body : JSON.stringify(req.body, null, 2));
+      } else {
+        console.log(`Captured ${items.length} API requests:\n`);
+        items.forEach((r, i) => {
+          const bodyPreview = r.body ? (typeof r.body === 'string' ? r.body.slice(0, 60) : JSON.stringify(r.body).slice(0, 60)) : '';
+          console.log(`  [${i}] ${r.method} ${r.status} ${r.url.slice(0, 80)}`);
+          if (bodyPreview) console.log(`      ${bodyPreview}...`);
+        });
+        console.log(`\nUse --detail <index> to see full response body.`);
+      }
+    }));
+
+  // ── Init (adapter scaffolding) ──
+
+  operate.command('init')
+    .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
+    .description('Generate adapter scaffold in ~/.opencli/clis/')
+    .action(async (name: string) => {
+      try {
+        const parts = name.split('/');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+          console.error('Name must be site/command format (e.g. hn/top)');
+          process.exitCode = EXIT_CODES.USAGE_ERROR;
+          return;
+        }
+        const [site, command] = parts;
+        if (!/^[a-zA-Z0-9_-]+$/.test(site) || !/^[a-zA-Z0-9_-]+$/.test(command)) {
+          console.error('Name parts must be alphanumeric/dash/underscore only');
+          process.exitCode = EXIT_CODES.USAGE_ERROR;
+          return;
+        }
+
+        const os = await import('node:os');
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const dir = path.join(os.homedir(), '.opencli', 'clis', site);
+        const filePath = path.join(dir, `${command}.ts`);
+
+        if (fs.existsSync(filePath)) {
+          console.log(`Adapter already exists: ${filePath}`);
+          return;
+        }
+
+        // Try to detect domain from last operate session
+        let domain = site;
+        try {
+          const page = await getOperatePage();
+          const url = await page.getCurrentUrl?.();
+          if (url) { try { domain = new URL(url).hostname; } catch {} }
+        } catch { /* no active session */ }
+
+        const template = `import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${site}',
+  name: '${command}',
+  description: '', // TODO: describe what this command does
+  domain: '${domain}',
+  strategy: Strategy.PUBLIC, // TODO: PUBLIC (no auth), COOKIE (needs login), UI (DOM interaction)
+  browser: false,            // TODO: set true if needs browser
+  args: [
+    { name: 'limit', type: 'int', default: 10, help: 'Number of items' },
+  ],
+  columns: [], // TODO: field names for table output (e.g. ['title', 'score', 'url'])
+  func: async (page, kwargs) => {
+    // TODO: implement data fetching
+    // Prefer API calls (fetch) over browser automation
+    // page is available if browser: true
+    return [];
+  },
+});
+`;
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, template, 'utf-8');
+        console.log(`Created: ${filePath}`);
+        console.log(`Edit the file to implement your adapter, then run: opencli operate verify ${name}`);
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      }
+    });
+
+  // ── Verify (test adapter) ──
+
+  operate.command('verify')
+    .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
+    .description('Execute an adapter and show results')
+    .action(async (name: string) => {
+      try {
+        const parts = name.split('/');
+        if (parts.length !== 2) { console.error('Name must be site/command format'); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        const [site, command] = parts;
+        if (!/^[a-zA-Z0-9_-]+$/.test(site) || !/^[a-zA-Z0-9_-]+$/.test(command)) {
+          console.error('Name parts must be alphanumeric/dash/underscore only');
+          process.exitCode = EXIT_CODES.USAGE_ERROR;
+          return;
+        }
+
+        const { execSync } = await import('node:child_process');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.ts`);
+
+        const fs = await import('node:fs');
+        if (!fs.existsSync(filePath)) {
+          console.error(`Adapter not found: ${filePath}`);
+          console.error(`Run "opencli operate init ${name}" to create it.`);
+          process.exitCode = EXIT_CODES.GENERIC_ERROR;
+          return;
+        }
+
+        console.log(`🔍 Verifying ${name}...\n`);
+        console.log(`  Loading: ${filePath}`);
+
+        try {
+          const output = execSync(`node dist/main.js ${site} ${command} --limit 3`, {
+            cwd: path.join(path.dirname(import.meta.url.replace('file://', '')), '..'),
+            timeout: 30000,
+            encoding: 'utf-8',
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          console.log(`  Executing: opencli ${site} ${command} --limit 3\n`);
+          console.log(output);
+          console.log(`\n  ✓ Adapter works!`);
+        } catch (err: any) {
+          console.log(`  Executing: opencli ${site} ${command} --limit 3\n`);
+          if (err.stdout) console.log(err.stdout);
+          if (err.stderr) console.error(err.stderr.slice(0, 500));
+          console.log(`\n  ✗ Adapter failed. Fix the code and try again.`);
+          process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      }
+    });
+
+  // ── Session ──
+
+  operate.command('close').description('Close the automation window')
+    .action(operateAction(async (page) => {
+      await page.closeWindow?.();
+      console.log('Automation window closed');
+    }));
+
   // ── Built-in: doctor / completion ──────────────────────────────────────────
 
   program

package/src/clis/twitter/article.ts

@@ -16,11 +16,41 @@ cli({
   ],
   columns: ['title', 'author', 'content', 'url'],
   func: async (page, kwargs) => {
-    // Extract tweet ID from URL if needed
+    // Extract tweet ID from URL if needed.
+    // Article URLs (x.com/i/article/{articleId}) use a different ID than
+    // tweet status URLs — the GraphQL endpoint needs the parent tweet ID.
     let tweetId = kwargs['tweet-id'];
+    const isArticleUrl = /\/article\/\d+/.test(tweetId);
     const urlMatch = tweetId.match(/\/(?:status|article)\/(\d+)/);
     if (urlMatch) tweetId = urlMatch[1];
 
+    if (isArticleUrl) {
+      // Navigate to the article page and resolve the parent tweet ID from DOM
+      await page.goto(`https://x.com/i/article/${tweetId}`);
+      await page.wait(3);
+      const resolvedId = await page.evaluate(`
+        (function() {
+          var links = document.querySelectorAll('a[href*="/status/"]');
+          for (var i = 0; i < links.length; i++) {
+            var m = links[i].href.match(/\\/status\\/(\\d+)/);
+            if (m) return m[1];
+          }
+          var og = document.querySelector('meta[property="og:url"]');
+          if (og && og.content) {
+            var m2 = og.content.match(/\\/status\\/(\\d+)/);
+            if (m2) return m2[1];
+          }
+          return null;
+        })()
+      `);
+      if (!resolvedId || typeof resolvedId !== 'string') {
+        throw new CommandExecutionError(
+          `Could not resolve article ${tweetId} to a tweet ID. The article page may not contain a linked tweet.`,
+        );
+      }
+      tweetId = resolvedId;
+    }
+
     // Navigate to the tweet page for cookie context
     await page.goto(`https://x.com/i/status/${tweetId}`);
     await page.wait(3);

package/src/clis/twitter/search.test.ts

@@ -153,15 +153,98 @@ describe('twitter search command', () => {
     expect(pushStateCall).toContain('f=top');
   });
 
+  it('falls back to search input when pushState fails twice', async () => {
+    const command = getRegistry().get('twitter/search');
+    expect(command?.func).toBeTypeOf('function');
+
+    const evaluate = vi.fn()
+      .mockResolvedValueOnce(undefined)     // pushState attempt 1
+      .mockResolvedValueOnce('/explore')    // pathname check 1 — not /search
+      .mockResolvedValueOnce(undefined)     // pushState attempt 2
+      .mockResolvedValueOnce('/explore')    // pathname check 2 — still not /search
+      .mockResolvedValueOnce({ ok: true })  // search input fallback succeeds
+      .mockResolvedValueOnce('/search');    // pathname check after fallback
+
+    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-99',
+                          content: {
+                            itemContent: {
+                              tweet_results: {
+                                result: {
+                                  rest_id: '99',
+                                  legacy: {
+                                    full_text: 'fallback works',
+                                    favorite_count: 3,
+                                    created_at: 'Wed Apr 02 12:00:00 +0000 2026',
+                                  },
+                                  core: {
+                                    user_results: {
+                                      result: {
+                                        core: { screen_name: 'bob' },
+                                      },
+                                    },
+                                  },
+                                  views: { count: '5' },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      ]),
+    };
+
+    const result = await command!.func!(page as any, { query: 'test fallback', filter: 'top', limit: 5 });
+
+    expect(result).toEqual([
+      {
+        id: '99',
+        author: 'bob',
+        text: 'fallback works',
+        created_at: 'Wed Apr 02 12:00:00 +0000 2026',
+        likes: 3,
+        views: '5',
+        url: 'https://x.com/i/status/99',
+      },
+    ]);
+    // 6 evaluate calls: 2x pushState + 2x pathname check + 1x fallback + 1x pathname check
+    expect(evaluate).toHaveBeenCalledTimes(6);
+    expect(page.autoScroll).toHaveBeenCalled();
+  });
+
   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');
+      .mockResolvedValueOnce(undefined)   // pushState attempt 1
+      .mockResolvedValueOnce('/explore')  // pathname check 1
+      .mockResolvedValueOnce(undefined)   // pushState attempt 2
+      .mockResolvedValueOnce('/login')    // pathname check 2
+      .mockResolvedValueOnce({ ok: false }); // search input fallback
 
     const page = {
       goto: vi.fn().mockResolvedValue(undefined),
@@ -177,6 +260,6 @@ describe('twitter search command', () => {
       .toThrow('Final path: /login');
     expect(page.autoScroll).not.toHaveBeenCalled();
     expect(page.getInterceptedRequests).not.toHaveBeenCalled();
-    expect(evaluate).toHaveBeenCalledTimes(4);
+    expect(evaluate).toHaveBeenCalledTimes(5);
   });
 });

package/src/clis/twitter/search.ts

@@ -3,16 +3,19 @@ import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
 
 /**
- * Trigger Twitter search SPA navigation and retry once on transient failures.
+ * Trigger Twitter search SPA navigation with fallback strategies.
  *
- * 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.
+ * Primary: pushState + popstate (works in most environments).
+ * Fallback: Type into the search input and press Enter when pushState fails
+ *   intermittently (e.g. due to Twitter A/B tests or timing races — see #690).
+ *
+ * Both strategies preserve the JS context so the fetch interceptor stays alive.
  */
 async function navigateToSearch(page: Pick<IPage, 'evaluate' | 'wait'>, query: string, filter: string): Promise<void> {
   const searchUrl = JSON.stringify(`/search?q=${encodeURIComponent(query)}&f=${filter}`);
   let lastPath = '';
 
+  // Strategy 1 (primary): pushState + popstate with retry
   for (let attempt = 1; attempt <= 2; attempt++) {
     await page.evaluate(`
       (() => {
@@ -20,7 +23,12 @@ async function navigateToSearch(page: Pick<IPage, 'evaluate' | 'wait'>, query: s
         window.dispatchEvent(new PopStateEvent('popstate', { state: {} }));
       })()
     `);
-    await page.wait({ selector: '[data-testid="primaryColumn"]' });
+
+    try {
+      await page.wait({ selector: '[data-testid="primaryColumn"]' });
+    } catch {
+      // selector timeout — fall through to path check or next attempt
+    }
 
     lastPath = String(await page.evaluate('() => window.location.pathname') || '');
     if (lastPath.startsWith('/search')) {
@@ -32,6 +40,61 @@ async function navigateToSearch(page: Pick<IPage, 'evaluate' | 'wait'>, query: s
     }
   }
 
+  // Strategy 2 (fallback): Use the search input on /explore.
+  // The nativeSetter + Enter approach triggers Twitter's own form handler,
+  // performing SPA navigation without a full page reload.
+  const queryStr = JSON.stringify(query);
+  const navResult = await page.evaluate(`(async () => {
+    try {
+      const input = document.querySelector('[data-testid="SearchBox_Search_Input"]');
+      if (!input) return { ok: false };
+
+      input.focus();
+      await new Promise(r => setTimeout(r, 300));
+
+      const nativeSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype, 'value'
+      )?.set;
+      if (!nativeSetter) return { ok: false };
+      nativeSetter.call(input, ${queryStr});
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+      await new Promise(r => setTimeout(r, 500));
+
+      input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Enter', code: 'Enter', keyCode: 13, bubbles: true
+      }));
+
+      return { ok: true };
+    } catch {
+      return { ok: false };
+    }
+  })()`);
+
+  if (navResult?.ok) {
+    try {
+      await page.wait({ selector: '[data-testid="primaryColumn"]' });
+    } catch {
+      // fall through to path check
+    }
+    lastPath = String(await page.evaluate('() => window.location.pathname') || '');
+    if (lastPath.startsWith('/search')) {
+      if (filter === 'live') {
+        await page.evaluate(`(() => {
+          const tabs = document.querySelectorAll('[role="tab"]');
+          for (const tab of tabs) {
+            if (tab.textContent.includes('Latest') || tab.textContent.includes('最新')) {
+              tab.click();
+              return;
+            }
+          }
+        })()`);
+        await page.wait(2);
+      }
+      return;
+    }
+  }
+
   throw new CommandExecutionError(
     `SPA navigation to /search failed. Final path: ${lastPath || '(empty)'}. Twitter may have changed its routing.`,
   );