feat(twitter): add lists command to retrieve user lists (#958)

* feat(twitter): add lists command to retrieve user lists

Add twitter/lists command that fetches Twitter/X lists for a user.
Supports:
- Lists with member and follower counts
- Private/public mode detection
- Default to current user if no user specified
- Works for any Twitter user

* docs: add lists command to twitter commands in README

Add twitter lists command to Built-in Commands table in both
English and Chinese README files

* fix(twitter): parse lists from card DOM instead of locale-specific page text

---------

Co-authored-by: isanwenyu <isanwenyu@users.noreply.github.com>
Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: isanwenyu

README.md

@@ -198,7 +198,7 @@ To load the source Browser Bridge extension:
 | **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `me` `subtitle` `user-videos` |
 | **tieba** | `hot` `posts` `search` `read` |
 | **hupu** | `hot` `search` `detail` `mentions` `reply` `like` `unlike` |
-| **twitter** | `trending` `search` `timeline` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
+| **twitter** | `trending` `search` `timeline` `lists` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
 | **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `upvoted` `save` `saved` `comment` `subscribe` |
 | **zhihu** | `hot` `search` `question` `download` `follow` `like` `favorite` `comment` `answer` |
 | **amazon** | `bestsellers` `search` `product` `offer` `discussion` `movers-shakers` `new-releases` |

README.zh-CN.md

@@ -184,7 +184,7 @@ npm link
 
 | 站点 | 命令 | 模式 |
 |------|------|------|
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` `accept` `reply-dm` `block` `unblock` `hide-reply` | 浏览器 |
+| **twitter** | `trending` `search` `timeline` `lists` `bookmarks` `profile` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` `accept` `reply-dm` `block` `unblock` `hide-reply` | 浏览器 |
 | **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 浏览器 |
 | **tieba** | `hot` `posts` `search` `read` | 浏览器 |
 | **hupu** | `hot` `search` `detail` `mentions` `reply` `like` `unlike` | 浏览器 |

clis/twitter/lists-parser.js

@@ -0,0 +1,77 @@
+const MEMBER_PATTERNS = [
+    /([\d.,]+(?:\s?[KMB千萬万亿])?)\s*members?/i,
+    /([\d.,]+(?:\s?[KMB千萬万亿])?)\s*位成员/,
+];
+const FOLLOWER_PATTERNS = [
+    /([\d.,]+(?:\s?[KMB千萬万亿])?)\s*followers?/i,
+    /([\d.,]+(?:\s?[KMB千萬万亿])?)\s*位关注者/,
+];
+const PRIVATE_PATTERNS = [/\bprivate\b/i, /锁定列表/];
+const EMPTY_STATE_PATTERNS = [
+    /hasn't created any lists/i,
+    /has not created any lists/i,
+    /no lists yet/i,
+    /没有创建任何列表/,
+    /还没有创建任何列表/,
+];
+function normalizeText(text) {
+    return String(text || '').replace(/\s+/g, ' ').trim();
+}
+function matchMetric(text, patterns) {
+    for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (match)
+            return normalizeText(match[1]);
+    }
+    return '0';
+}
+function looksLikeMetadata(line) {
+    const text = normalizeText(line);
+    if (!text)
+        return true;
+    if (text.startsWith('@'))
+        return true;
+    if (MEMBER_PATTERNS.some((pattern) => pattern.test(text)))
+        return true;
+    if (FOLLOWER_PATTERNS.some((pattern) => pattern.test(text)))
+        return true;
+    if (PRIVATE_PATTERNS.some((pattern) => pattern.test(text)))
+        return true;
+    if (/^(public|pinned)$/i.test(text))
+        return true;
+    if (/^(lists?|你的列表)$/i.test(text))
+        return true;
+    return false;
+}
+export function parseListCards(cards) {
+    const seen = new Set();
+    const results = [];
+    for (const card of cards || []) {
+        const href = normalizeText(card?.href);
+        const rawText = String(card?.text || '');
+        if (!href || seen.has(href))
+            continue;
+        seen.add(href);
+        const text = normalizeText(rawText);
+        if (!text)
+            continue;
+        const lines = rawText
+            .split('\n')
+            .map((line) => normalizeText(line))
+            .filter(Boolean);
+        const name = lines.find((line) => !looksLikeMetadata(line));
+        if (!name)
+            continue;
+        results.push({
+            name,
+            members: matchMetric(text, MEMBER_PATTERNS),
+            followers: matchMetric(text, FOLLOWER_PATTERNS),
+            mode: PRIVATE_PATTERNS.some((pattern) => pattern.test(text)) ? 'private' : 'public',
+        });
+    }
+    return results;
+}
+export function isEmptyListsState(text) {
+    const normalized = normalizeText(text);
+    return EMPTY_STATE_PATTERNS.some((pattern) => pattern.test(normalized));
+}

clis/twitter/lists.d.ts

@@ -0,0 +1,5 @@
+import { Argument, Column } from '@jackwener/opencli/types';
+declare const args: Argument[];
+declare const columns: Column[];
+export { args, columns };
+export default {};

clis/twitter/lists.js

@@ -0,0 +1,62 @@
+import { AuthRequiredError, SelectorError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { isEmptyListsState, parseListCards } from './lists-parser.js';
+
+cli({
+    site: 'twitter',
+    name: 'lists',
+    description: 'Get Twitter/X lists for a user',
+    domain: 'x.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'user', positional: true, type: 'string', required: false },
+        { name: 'limit', type: 'int', default: 50 },
+    ],
+    columns: ['name', 'members', 'followers', 'mode'],
+    func: async (page, kwargs) => {
+        let targetUser = kwargs.user;
+        if (!targetUser) {
+            await page.goto('https://x.com/home');
+            await page.wait({ selector: '[data-testid="primaryColumn"]' });
+            const href = await page.evaluate(`() => {
+            const link = document.querySelector('a[data-testid="AppTabBar_Profile_Link"]');
+            return link ? link.getAttribute('href') : null;
+        }`);
+            if (!href) {
+                throw new AuthRequiredError('x.com', 'Could not find logged-in user profile link. Are you logged in?');
+            }
+            targetUser = href.replace('/', '');
+        }
+        await page.goto(`https://x.com/${targetUser}/lists`);
+        await page.wait(3);
+        const pageData = await page.evaluate(`() => {
+            const cards = [];
+            const seen = new Set();
+            for (const anchor of Array.from(document.querySelectorAll('a[href*="/i/lists/"]'))) {
+                const href = anchor.getAttribute('href') || '';
+                if (!/\\/i\\/lists\\/\\d+/.test(href) || seen.has(href)) continue;
+                seen.add(href);
+                const container = anchor.closest('[data-testid="cellInnerDiv"]') || anchor;
+                const text = (container.innerText || anchor.innerText || '').trim();
+                if (!text) continue;
+                cards.push({ href, text });
+            }
+            return {
+                cards,
+                pageText: document.body.innerText || '',
+            };
+        }`);
+        if (!pageData?.pageText) {
+            throw new SelectorError('Twitter lists', 'Empty page text');
+        }
+        const results = parseListCards(pageData.cards);
+        if (results.length === 0) {
+            if (isEmptyListsState(pageData.pageText)) {
+                return [];
+            }
+            throw new SelectorError('Twitter lists', `Could not parse list data`);
+        }
+        return results.slice(0, kwargs.limit);
+    }
+});

clis/twitter/lists.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { isEmptyListsState, parseListCards } from './lists-parser.js';
+
+describe('twitter lists parser', () => {
+    it('parses english list cards without relying on page locale', () => {
+        const result = parseListCards([
+            {
+                href: '/i/lists/123',
+                text: `AI Researchers
+@jack
+124 Members 3.4K Followers
+Private`,
+            },
+        ]);
+        expect(result).toEqual([
+            {
+                name: 'AI Researchers',
+                members: '124',
+                followers: '3.4K',
+                mode: 'private',
+            },
+        ]);
+    });
+
+    it('parses chinese list cards without scanning document.body.innerText', () => {
+        const result = parseListCards([
+            {
+                href: '/i/lists/456',
+                text: `AI观察
+@jack
+321 位成员 8.8K 位关注者
+锁定列表`,
+            },
+        ]);
+        expect(result).toEqual([
+            {
+                name: 'AI观察',
+                members: '321',
+                followers: '8.8K',
+                mode: 'private',
+            },
+        ]);
+    });
+
+    it('detects empty state text in english and chinese', () => {
+        expect(isEmptyListsState(`@jack hasn't created any Lists yet`)).toBe(true);
+        expect(isEmptyListsState('这个账号还没有创建任何列表')).toBe(true);
+        expect(isEmptyListsState('AI Researchers 124 Members')).toBe(false);
+    });
+});