@jackwener/opencli 1.7.13 → 1.7.15

package/clis/twitter/retweet.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './retweet.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter retweet command', () => {
+    it('clicks the retweet button then the confirm menu item and reports success', async () => {
+        const cmd = getRegistry().get('twitter/retweet');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Tweet successfully retweeted.' },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(page.goto).toHaveBeenCalledWith('https://x.com/alice/status/2040254679301718161');
+        expect(page.wait).toHaveBeenNthCalledWith(1, { selector: '[data-testid="primaryColumn"]' });
+        expect(page.wait).toHaveBeenNthCalledWith(2, 2);
+        const script = page.evaluate.mock.calls[0][0];
+        // Two-step UI flow must be present:
+        //   1) click the retweet button
+        //   2) wait for and click the confirm menu item (data-testid="retweetConfirm")
+        expect(script).toContain('retweetBtn.click()');
+        expect(script).toContain("document.querySelector('[data-testid=\"retweetConfirm\"]')");
+        expect(script).toContain('confirmBtn.click()');
+        // Article scoping comes from the shared helper (buildTwitterArticleScopeSource):
+        // emits __twHasLinkToTarget + __twGetStatusIdFromHref + the anchored
+        // tweet-path regex. JSDOM-level coverage lives in shared.test.js.
+        expect(script).toContain('__twHasLinkToTarget');
+        expect(script).toContain('__twGetStatusIdFromHref');
+        expect(script).toContain("document.querySelectorAll('article')");
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"retweet\"]')");
+        // Idempotency probe: when already retweeted ([data-testid="unretweet"] present),
+        // the script returns ok:true with an "already retweeted" message.
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"unretweet\"]')");
+        expect(result).toEqual([
+            { status: 'success', message: 'Tweet successfully retweeted.' },
+        ]);
+    });
+
+    it('returns a failed row when the confirm menu item never appears', async () => {
+        const cmd = getRegistry().get('twitter/retweet');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: false, message: 'Retweet menu opened but the confirm option did not appear.' },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(result).toEqual([
+            { status: 'failed', message: 'Retweet menu opened but the confirm option did not appear.' },
+        ]);
+        expect(page.wait).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws CommandExecutionError when no page is provided', async () => {
+        const cmd = getRegistry().get('twitter/retweet');
+        await expect(cmd.func(undefined, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('rejects invalid tweet URLs before navigation', async () => {
+        const cmd = getRegistry().get('twitter/retweet');
+        const page = createPageMock([]);
+        await expect(cmd.func(page, {
+            url: 'https://evil.com/?next=https://x.com/alice/status/2040254679301718161',
+        })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});

package/clis/twitter/search.js

@@ -1,6 +1,104 @@
-import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { extractMedia } from './shared.js';
+import { applyTopByEngagement } from './utils.js';
+
+// ── Public-search operator surface ─────────────────────────────────────
+//
+// X's web search supports a small set of inline operators (from:, filter:,
+// -filter:, etc.) plus a tab-selector URL param `f=`. We expose the most
+// useful subset as flags so callers don't have to memorise the operator
+// strings, while still letting power users append raw operators in <query>.
+
+/** Operands accepted by `--has`. Map 1:1 to Twitter's `filter:<x>` operator. */
+const HAS_CHOICES = Object.freeze(['media', 'images', 'videos', 'links', 'replies']);
+
+/**
+ * Operands accepted by `--exclude`. Note that `retweets` is exposed as the
+ * friendlier name but X's actual operator stays as `-filter:nativeretweets`
+ * (the historical "native" prefix is preserved by their backend).
+ */
+const EXCLUDE_CHOICES = Object.freeze(['replies', 'retweets', 'media', 'links']);
+
+/**
+ * Operands accepted by `--product`. `photos`/`videos` are the human-friendly
+ * forms used by the X UI tabs; the URL param uses the singular forms (image,
+ * video). `people` is intentionally NOT supported here because that tab
+ * returns User objects, not tweets, and would need a different output schema.
+ */
+const PRODUCT_CHOICES = Object.freeze(['top', 'live', 'photos', 'videos']);
+
+const PRODUCT_TO_F_PARAM = Object.freeze({
+    top: 'top',
+    live: 'live',
+    photos: 'image',
+    videos: 'video',
+});
+
+const FROM_USER_PATTERN = /^[A-Za-z0-9_]{1,15}$/;
+
+const EXCLUDE_TO_OPERATOR = Object.freeze({
+    replies: '-filter:replies',
+    // `retweets` is a CLI-friendly alias for X's actual `-filter:nativeretweets`.
+    retweets: '-filter:nativeretweets',
+    media: '-filter:media',
+    links: '-filter:links',
+});
+
+/**
+ * Compose the final search query string by appending operator clauses for
+ * --from / --has / --exclude. Pure synchronous — exported via __test__ for
+ * unit coverage.
+ *
+ * Behaviour notes:
+ * - Trims leading `@` from --from so callers can pass `@alice` or `alice`.
+ * - Order is `<query> from:X filter:Y -filter:Z` (matches what X's own search
+ *   bar emits when you click the suggestions UI).
+ * - Empty <query> with non-empty filters is allowed — the resulting string
+ *   is just the operator clauses joined; X handles that fine.
+ *
+ * @param {string} rawQuery
+ * @param {{ from?: string, has?: string, exclude?: string }} kwargs
+ * @returns {string}
+ */
+function buildSearchQuery(rawQuery, kwargs) {
+    const parts = [String(rawQuery ?? '').trim()];
+    if (kwargs.from) {
+        const fromUser = String(kwargs.from).trim().replace(/^@+/, '');
+        if (fromUser && !FROM_USER_PATTERN.test(fromUser)) {
+            throw new ArgumentError(
+                `Invalid --from username: ${JSON.stringify(kwargs.from)}`,
+                'Use a Twitter/X handle with 1-15 letters, numbers, or underscores; omit @ or pass @handle.',
+            );
+        }
+        if (fromUser) parts.push(`from:${fromUser}`);
+    }
+    if (kwargs.has) {
+        parts.push(`filter:${kwargs.has}`);
+    }
+    if (kwargs.exclude) {
+        const op = EXCLUDE_TO_OPERATOR[kwargs.exclude];
+        if (op) parts.push(op);
+    }
+    return parts.filter(Boolean).join(' ');
+}
+
+/**
+ * Resolve which X search tab (`f=` URL param) to land on. `--product` wins
+ * over the legacy `--filter` so adding `--product` doesn't break callers that
+ * were already setting `--filter top|live`.
+ *
+ * @param {{ product?: string, filter?: string }} kwargs
+ * @returns {string} URL `f=` value: top|live|image|video
+ */
+function resolveSearchFParam(kwargs) {
+    if (kwargs.product) {
+        const mapped = PRODUCT_TO_F_PARAM[kwargs.product];
+        if (mapped) return mapped;
+    }
+    return kwargs.filter === 'live' ? 'live' : 'top';
+}
+
 /**
  * Trigger Twitter search SPA navigation with fallback strategies.
  *
@@ -9,9 +107,13 @@ import { extractMedia } from './shared.js';
  *   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.
+ *
+ * @param {object} page
+ * @param {string} query  — final composed query (already merged with operators)
+ * @param {string} fParam — Twitter URL `f=` value (top|live|image|video)
  */
-async function navigateToSearch(page, query, filter) {
-    const searchUrl = JSON.stringify(`/search?q=${encodeURIComponent(query)}&f=${filter}`);
+async function navigateToSearch(page, query, fParam) {
+    const searchUrl = JSON.stringify(`/search?q=${encodeURIComponent(query)}&f=${fParam}`);
     let lastPath = '';
     // Strategy 1 (primary): pushState + popstate with retry
     for (let attempt = 1; attempt <= 2; attempt++) {
@@ -74,40 +176,78 @@ async function navigateToSearch(page, query, filter) {
         }
         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);
+            // The fallback path doesn't carry the f= URL param, so click the
+            // matching tab to align with the requested product. Only `live`
+            // currently surfaces a distinct tab label — `image`/`video` tabs
+            // also need an explicit click, so try them all.
+            const tabClicked = await clickProductTabIfNeeded(page, fParam);
+            if (!tabClicked) {
+                throw new CommandExecutionError(`SPA fallback reached /search but could not select the requested product tab: ${fParam}`);
             }
             return;
         }
     }
     throw new CommandExecutionError(`SPA navigation to /search failed. Final path: ${lastPath || '(empty)'}. Twitter may have changed its routing.`);
 }
+
+/**
+ * After the search-input fallback lands on /search, the f= param is missing
+ * from the URL. Click the matching tab in the result page header so the
+ * SearchTimeline call uses the right filter. No-op for fParam=top (default).
+ */
+async function clickProductTabIfNeeded(page, fParam) {
+    if (fParam === 'top') return true;
+    const tabLabels = JSON.stringify({
+        live: ['Latest', '最新'],
+        image: ['Photos', 'Images', '照片', '图片'],
+        video: ['Videos', '视频'],
+    }[fParam] || []);
+    if (tabLabels === '[]') return true;
+    const clicked = await page.evaluate(`(() => {
+      const labels = ${tabLabels};
+      const tabs = document.querySelectorAll('[role="tab"]');
+      for (const tab of tabs) {
+        const txt = (tab.textContent || '').trim();
+        if (labels.some(l => txt.includes(l))) {
+          tab.click();
+          return true;
+        }
+      }
+      return false;
+    })()`);
+    if (!clicked) return false;
+    await page.wait(2);
+    return true;
+}
+
 cli({
     site: 'twitter',
     name: 'search',
     access: 'read',
-    description: 'Search Twitter/X for tweets',
+    description: 'Search Twitter/X for tweets, with optional --from / --has / --exclude / --product filters mapped to X\'s search operators',
     domain: 'x.com',
     strategy: Strategy.INTERCEPT, // Use intercept strategy
     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 },
+        { name: 'query', type: 'string', required: true, positional: true, help: 'Search query. Raw X operators (e.g. "exact phrase", #tag, OR, lang:en, since:YYYY-MM-DD, from:, since:) are passed through unchanged.' },
+        { name: 'filter', type: 'string', default: 'top', choices: ['top', 'live'], help: 'Legacy alias for --product. Kept for backwards compatibility; if --product is set it wins.' },
+        { name: 'product', type: 'string', choices: PRODUCT_CHOICES, help: 'Which X search tab to read: top (default), live (Latest), photos, videos. Maps to the f= URL param.' },
+        { name: 'from', type: 'string', help: 'Restrict to tweets authored by <user>. Leading @ is stripped. Equivalent to appending `from:<user>` to the query.' },
+        { name: 'has', type: 'string', choices: HAS_CHOICES, help: 'Restrict to tweets that have media|images|videos|links|replies. Maps to X\'s `filter:<has>` operator.' },
+        { name: 'exclude', type: 'string', choices: EXCLUDE_CHOICES, help: 'Exclude tweets matching <type>: replies|retweets|media|links. Maps to X\'s `-filter:<x>` operator (retweets → -filter:nativeretweets).' },
+        { name: 'limit', type: 'int', default: 15, help: 'Maximum number of tweets to return (default 15). Result count after server-side filtering.' },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the results by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps X\'s native ordering.' },
     ],
     columns: ['id', 'author', 'text', 'created_at', 'likes', 'views', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
-        const query = kwargs.query;
-        const filter = kwargs.filter === 'live' ? 'live' : 'top';
+        const finalQuery = buildSearchQuery(kwargs.query, kwargs);
+        if (!finalQuery) {
+            throw new ArgumentError('twitter search query is empty', 'Provide a non-empty <query>, or use at least one of --from / --has / --exclude.');
+        }
+        if (!Number.isInteger(Number(kwargs.limit)) || Number(kwargs.limit) <= 0) {
+            throw new ArgumentError('twitter search --limit must be a positive integer', 'Example: opencli twitter search opencli --limit 15');
+        }
+        const fParam = resolveSearchFParam(kwargs);
         // 1. Navigate to x.com/explore (has a search input at the top)
         await page.goto('https://x.com/explore');
         await page.wait(3);
@@ -120,10 +260,10 @@ 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.
-        await navigateToSearch(page, query, filter);
+        await navigateToSearch(page, finalQuery, fParam);
         // 4. Scroll to trigger additional pagination
         await page.autoScroll({ times: 3, delayMs: 2000 });
-        // 6. Retrieve captured data
+        // 5. Retrieve captured data
         const requests = await page.getInterceptedRequests();
         if (!requests || requests.length === 0)
             return [];
@@ -167,6 +307,18 @@ cli({
                 // ignore parsing errors for individual payloads
             }
         }
-        return results.slice(0, kwargs.limit);
+        const trimmed = results.slice(0, kwargs.limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     }
 });
+
+export const __test__ = {
+    buildSearchQuery,
+    resolveSearchFParam,
+    HAS_CHOICES,
+    EXCLUDE_CHOICES,
+    PRODUCT_CHOICES,
+    EXCLUDE_TO_OPERATOR,
+    PRODUCT_TO_F_PARAM,
+    FROM_USER_PATTERN,
+};

package/clis/twitter/search.test.js

@@ -1,6 +1,8 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
-import './search.js';
+import { __test__ } from './search.js';
+
+const { buildSearchQuery, resolveSearchFParam, HAS_CHOICES, EXCLUDE_CHOICES, PRODUCT_CHOICES, EXCLUDE_TO_OPERATOR, PRODUCT_TO_F_PARAM, FROM_USER_PATTERN } = __test__;
 describe('twitter search command', () => {
     it('retries transient SPA navigation failures before giving up', async () => {
         const command = getRegistry().get('twitter/search');
@@ -213,6 +215,56 @@ describe('twitter search command', () => {
         expect(evaluate).toHaveBeenCalledTimes(6);
         expect(page.autoScroll).toHaveBeenCalled();
     });
+    it('clicks the requested product tab after fallback navigation when f= param is absent', async () => {
+        const command = getRegistry().get('twitter/search');
+        expect(command?.func).toBeTypeOf('function');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined) // pushState attempt 1
+            .mockResolvedValueOnce('/explore')
+            .mockResolvedValueOnce(undefined) // pushState attempt 2
+            .mockResolvedValueOnce('/explore')
+            .mockResolvedValueOnce({ ok: true }) // search input fallback
+            .mockResolvedValueOnce('/search')
+            .mockResolvedValueOnce(true); // product tab click
+        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([]),
+        };
+        const result = await command.func(page, { query: 'cats', product: 'photos', limit: 5 });
+        expect(result).toEqual([]);
+        expect(evaluate).toHaveBeenCalledTimes(7);
+        expect(evaluate.mock.calls[6][0]).toContain('Photos');
+        expect(page.autoScroll).toHaveBeenCalled();
+    });
+    it('throws when fallback navigation cannot select the requested product tab', async () => {
+        const command = getRegistry().get('twitter/search');
+        expect(command?.func).toBeTypeOf('function');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined) // pushState attempt 1
+            .mockResolvedValueOnce('/explore')
+            .mockResolvedValueOnce(undefined) // pushState attempt 2
+            .mockResolvedValueOnce('/explore')
+            .mockResolvedValueOnce({ ok: true }) // search input fallback
+            .mockResolvedValueOnce('/search')
+            .mockResolvedValueOnce(false); // requested tab missing
+        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: 'cats', product: 'videos', limit: 5 }))
+            .rejects
+            .toThrow(/could not select the requested product tab: video/);
+        expect(page.autoScroll).not.toHaveBeenCalled();
+        expect(page.getInterceptedRequests).not.toHaveBeenCalled();
+    });
     it('throws with the final path after both attempts fail', async () => {
         const command = getRegistry().get('twitter/search');
         expect(command?.func).toBeTypeOf('function');
@@ -238,3 +290,216 @@ describe('twitter search command', () => {
         expect(evaluate).toHaveBeenCalledTimes(5);
     });
 });
+
+describe('twitter search filter helpers', () => {
+    describe('buildSearchQuery', () => {
+        it('returns the trimmed raw query when no filters are set', () => {
+            expect(buildSearchQuery('  hello world  ', {})).toBe('hello world');
+        });
+        it('appends from: with leading @ stripped', () => {
+            expect(buildSearchQuery('hello', { from: '@alice' })).toBe('hello from:alice');
+        });
+        it('preserves from: when caller passes a bare username', () => {
+            expect(buildSearchQuery('hello', { from: 'alice' })).toBe('hello from:alice');
+        });
+        it('strips multiple leading @ characters from --from', () => {
+            expect(buildSearchQuery('hi', { from: '@@bob' })).toBe('hi from:bob');
+        });
+        it('drops --from when it is whitespace-only', () => {
+            expect(buildSearchQuery('hi', { from: '   ' })).toBe('hi');
+        });
+        it('rejects invalid --from usernames instead of injecting raw operators', () => {
+            expect(() => buildSearchQuery('hi', { from: 'alice filter:links' })).toThrow(/Invalid --from/);
+            expect(() => buildSearchQuery('hi', { from: 'alice/bob' })).toThrow(/Invalid --from/);
+            expect(() => buildSearchQuery('hi', { from: '@' + 'a'.repeat(16) })).toThrow(/Invalid --from/);
+        });
+        it('appends filter:<has> for --has', () => {
+            expect(buildSearchQuery('q', { has: 'images' })).toBe('q filter:images');
+        });
+        it('maps --exclude retweets to -filter:nativeretweets', () => {
+            expect(buildSearchQuery('q', { exclude: 'retweets' })).toBe('q -filter:nativeretweets');
+        });
+        it('maps --exclude replies/media/links to their -filter operators', () => {
+            expect(buildSearchQuery('q', { exclude: 'replies' })).toBe('q -filter:replies');
+            expect(buildSearchQuery('q', { exclude: 'media' })).toBe('q -filter:media');
+            expect(buildSearchQuery('q', { exclude: 'links' })).toBe('q -filter:links');
+        });
+        it('silently ignores unknown --exclude values', () => {
+            // choices: ['replies','retweets','media','links'] — unknowns shouldn't appear
+            // in real CLI use because the validator rejects them, but the helper still
+            // guards via the EXCLUDE_TO_OPERATOR map lookup.
+            expect(buildSearchQuery('q', { exclude: 'bogus' })).toBe('q');
+        });
+        it('composes multiple filter clauses in stable order: query → from → has → exclude', () => {
+            expect(buildSearchQuery('hot take', {
+                from: '@alice',
+                has: 'media',
+                exclude: 'retweets',
+            })).toBe('hot take from:alice filter:media -filter:nativeretweets');
+        });
+        it('allows an empty raw query when filters are present', () => {
+            expect(buildSearchQuery('', { from: 'alice' })).toBe('from:alice');
+        });
+        it('returns empty string when nothing useful is supplied', () => {
+            expect(buildSearchQuery('', {})).toBe('');
+            expect(buildSearchQuery('   ', {})).toBe('');
+        });
+        it('coerces nullish raw query into empty string', () => {
+            expect(buildSearchQuery(null, { from: 'alice' })).toBe('from:alice');
+            expect(buildSearchQuery(undefined, { from: 'alice' })).toBe('from:alice');
+        });
+    });
+
+    describe('resolveSearchFParam', () => {
+        it('defaults to top when neither product nor filter is set', () => {
+            expect(resolveSearchFParam({})).toBe('top');
+        });
+        it('returns top when filter=top', () => {
+            expect(resolveSearchFParam({ filter: 'top' })).toBe('top');
+        });
+        it('returns live when filter=live', () => {
+            expect(resolveSearchFParam({ filter: 'live' })).toBe('live');
+        });
+        it('maps --product photos to image (Twitter URL singular form)', () => {
+            expect(resolveSearchFParam({ product: 'photos' })).toBe('image');
+        });
+        it('maps --product videos to video (Twitter URL singular form)', () => {
+            expect(resolveSearchFParam({ product: 'videos' })).toBe('video');
+        });
+        it('maps --product top|live straight through', () => {
+            expect(resolveSearchFParam({ product: 'top' })).toBe('top');
+            expect(resolveSearchFParam({ product: 'live' })).toBe('live');
+        });
+        it('lets --product win when both --product and --filter are set', () => {
+            expect(resolveSearchFParam({ product: 'photos', filter: 'live' })).toBe('image');
+            expect(resolveSearchFParam({ product: 'top', filter: 'live' })).toBe('top');
+        });
+        it('falls back to filter when --product is unknown', () => {
+            // unknowns are blocked at the CLI validator layer; this is just defence
+            expect(resolveSearchFParam({ product: 'bogus', filter: 'live' })).toBe('live');
+            expect(resolveSearchFParam({ product: 'bogus' })).toBe('top');
+        });
+    });
+
+    describe('choice surface', () => {
+        it('exposes the documented HAS_CHOICES set', () => {
+            expect(HAS_CHOICES).toEqual(['media', 'images', 'videos', 'links', 'replies']);
+        });
+        it('exposes the documented EXCLUDE_CHOICES set', () => {
+            expect(EXCLUDE_CHOICES).toEqual(['replies', 'retweets', 'media', 'links']);
+        });
+        it('exposes the documented PRODUCT_CHOICES set', () => {
+            expect(PRODUCT_CHOICES).toEqual(['top', 'live', 'photos', 'videos']);
+        });
+        it('keeps PRODUCT_TO_F_PARAM domain a strict subset of PRODUCT_CHOICES', () => {
+            for (const choice of PRODUCT_CHOICES) {
+                expect(PRODUCT_TO_F_PARAM[choice]).toBeTypeOf('string');
+            }
+        });
+        it('keeps EXCLUDE_TO_OPERATOR domain a strict subset of EXCLUDE_CHOICES', () => {
+            for (const choice of EXCLUDE_CHOICES) {
+                expect(EXCLUDE_TO_OPERATOR[choice]).toMatch(/^-filter:/);
+            }
+        });
+        it('keeps FROM_USER_PATTERN aligned with X handle syntax', () => {
+            expect(FROM_USER_PATTERN.test('alice_123')).toBe(true);
+            expect(FROM_USER_PATTERN.test('a'.repeat(15))).toBe(true);
+            expect(FROM_USER_PATTERN.test('a'.repeat(16))).toBe(false);
+            expect(FROM_USER_PATTERN.test('alice/bob')).toBe(false);
+        });
+    });
+});
+
+describe('twitter search end-to-end with new filters', () => {
+    it('encodes the composed query and product=live into the f= URL param', 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',
+            from: '@alice',
+            has: 'images',
+            exclude: 'retweets',
+            product: 'live',
+            limit: 5,
+        });
+        const pushStateCall = evaluate.mock.calls[0][0];
+        // f=live wins because --product=live trumps the default --filter
+        expect(pushStateCall).toContain('f=live');
+        // composed query should be percent-encoded inside the URL
+        const encoded = encodeURIComponent('breaking news from:alice filter:images -filter:nativeretweets');
+        expect(pushStateCall).toContain(encoded);
+    });
+    it('throws ArgumentError when query and all filters are empty', async () => {
+        const command = getRegistry().get('twitter/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            installInterceptor: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn(),
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            getInterceptedRequests: vi.fn(),
+        };
+        await expect(command.func(page, { query: '   ', limit: 5 }))
+            .rejects
+            .toThrow(/empty/i);
+        expect(page.installInterceptor).not.toHaveBeenCalled();
+    });
+    it('throws ArgumentError for invalid --from before navigation', async () => {
+        const command = getRegistry().get('twitter/search');
+        const page = {
+            goto: vi.fn(),
+            wait: vi.fn(),
+            installInterceptor: vi.fn(),
+            evaluate: vi.fn(),
+            autoScroll: vi.fn(),
+            getInterceptedRequests: vi.fn(),
+        };
+        await expect(command.func(page, { query: 'hi', from: 'alice filter:links', limit: 5 }))
+            .rejects
+            .toThrow(/Invalid --from/);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+    it('throws ArgumentError for invalid --limit before navigation', async () => {
+        const command = getRegistry().get('twitter/search');
+        const page = {
+            goto: vi.fn(),
+            wait: vi.fn(),
+            installInterceptor: vi.fn(),
+            evaluate: vi.fn(),
+            autoScroll: vi.fn(),
+            getInterceptedRequests: vi.fn(),
+        };
+        await expect(command.func(page, { query: 'hi', limit: 0 }))
+            .rejects
+            .toThrow(/--limit/);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+    it('runs with only filters set (empty <query>)', 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([]),
+        };
+        const result = await command.func(page, { query: '', from: 'alice', limit: 5 });
+        expect(result).toEqual([]);
+        const pushStateCall = evaluate.mock.calls[0][0];
+        expect(pushStateCall).toContain(encodeURIComponent('from:alice'));
+    });
+});