@jackwener/opencli 1.7.13 → 1.7.15

package/clis/twitter/shared.js

@@ -1,4 +1,83 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+
 const QUERY_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const TWEET_PATH_PATTERN = /^\/(?:[^/]+|i)\/status\/(\d+)\/?$/;
+const TWEET_HOSTS = new Set(['x.com', 'twitter.com']);
+
+function isTwitterHost(hostname) {
+    return TWEET_HOSTS.has(hostname)
+        || hostname.endsWith('.x.com')
+        || hostname.endsWith('.twitter.com');
+}
+
+export function parseTweetUrl(rawUrl) {
+    const value = String(rawUrl ?? '').trim();
+    if (!value) {
+        throw new ArgumentError('twitter tweet URL cannot be empty', 'Example: opencli twitter retweet https://x.com/jack/status/20');
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new ArgumentError(`Invalid tweet URL: ${value}`, 'Use a full https://x.com/<user>/status/<id> URL');
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (parsed.protocol !== 'https:' || !isTwitterHost(hostname)) {
+        throw new ArgumentError(`Invalid tweet URL host: ${value}`, 'Use a full https://x.com/<user>/status/<id> URL');
+    }
+    const match = parsed.pathname.match(TWEET_PATH_PATTERN);
+    if (!match?.[1]) {
+        throw new ArgumentError(`Could not extract tweet ID from URL: ${value}`, 'Use a full https://x.com/<user>/status/<id> URL');
+    }
+    return {
+        id: match[1],
+        url: parsed.toString(),
+    };
+}
+
+/**
+ * Build a JS source fragment that, when embedded inside a `page.evaluate(...)`
+ * IIFE, declares browser-side helpers for scoping operations to a specific
+ * tweet by status id. Sibling adapters historically inlined ad-hoc article
+ * lookups that either (a) skipped scoping entirely (silent: act on first
+ * matching button on a conversation page) or (b) used substring matches like
+ * `pathname.includes('/status/' + tweetId)` (silent: `/status/123` matches
+ * `/status/1234567`). This helper centralises the canonical pattern so all
+ * write-actions reuse the same exact-match guard.
+ *
+ * Declared bindings (available to the embedding IIFE):
+ *   - `tweetId`                       : the requested status id (string)
+ *   - `__twGetStatusIdFromHref(href)` : extract status id from a link href, or null
+ *   - `__twHasLinkToTarget(root)`     : true iff `root` contains any link to tweetId
+ *   - `findTargetArticle()`           : the <article> matching tweetId, or undefined
+ */
+export function buildTwitterArticleScopeSource(tweetId) {
+    return `
+        const tweetId = ${JSON.stringify(tweetId)};
+        const __twTweetPathRe = /^\\/(?:[^/]+|i)\\/status\\/(\\d+)\\/?$/;
+        const __twIsTwitterHost = (hostname) => hostname === 'x.com'
+            || hostname === 'twitter.com'
+            || hostname.endsWith('.x.com')
+            || hostname.endsWith('.twitter.com');
+        const __twGetStatusIdFromHref = (href) => {
+            try {
+                const parsed = new URL(href, window.location.origin);
+                if (parsed.protocol !== 'https:' || !__twIsTwitterHost(parsed.hostname.toLowerCase())) {
+                    return null;
+                }
+                return parsed.pathname.match(__twTweetPathRe)?.[1] || null;
+            } catch {
+                return null;
+            }
+        };
+        const __twHasLinkToTarget = (root) => Array.from(root.querySelectorAll('a[href*="/status/"]'))
+            .some((link) => __twGetStatusIdFromHref(link.href) === tweetId);
+        const findTargetArticle = () => Array.from(document.querySelectorAll('article'))
+            .find(__twHasLinkToTarget);
+    `;
+}
+
 export function sanitizeQueryId(resolved, fallbackId) {
     return typeof resolved === 'string' && QUERY_ID_PATTERN.test(resolved) ? resolved : fallbackId;
 }
@@ -65,4 +144,6 @@ export function extractMedia(legacy) {
 export const __test__ = {
     sanitizeQueryId,
     extractMedia,
+    parseTweetUrl,
+    buildTwitterArticleScopeSource,
 };

package/clis/twitter/shared.test.js

@@ -1,7 +1,140 @@
 import { describe, expect, it } from 'vitest';
+import { JSDOM } from 'jsdom';
 import { __test__ } from './shared.js';
+import { ArgumentError } from '@jackwener/opencli/errors';
 
-const { extractMedia } = __test__;
+const { extractMedia, parseTweetUrl, buildTwitterArticleScopeSource } = __test__;
+
+describe('twitter parseTweetUrl', () => {
+    it('accepts exact Twitter/X tweet URLs and preserves query parameters', () => {
+        expect(parseTweetUrl('https://x.com/alice/status/2040254679301718161?s=20')).toEqual({
+            id: '2040254679301718161',
+            url: 'https://x.com/alice/status/2040254679301718161?s=20',
+        });
+        expect(parseTweetUrl('https://mobile.twitter.com/i/status/2040318731105313143')).toEqual({
+            id: '2040318731105313143',
+            url: 'https://mobile.twitter.com/i/status/2040318731105313143',
+        });
+    });
+
+    it('rejects non-https, off-domain, host-suffix, embedded, and path-suffix URLs', () => {
+        const invalid = [
+            'http://x.com/alice/status/2040254679301718161',
+            'https://evil.com/alice/status/2040254679301718161',
+            'https://x.com.evil.com/alice/status/2040254679301718161',
+            'https://evil.com/?next=https://x.com/alice/status/2040254679301718161',
+            'https://x.com/alice/status/2040254679301718161/photo/1',
+        ];
+        for (const url of invalid) {
+            expect(() => parseTweetUrl(url)).toThrow(ArgumentError);
+        }
+    });
+});
+
+describe('twitter buildTwitterArticleScopeSource', () => {
+    // JSDOM-based tests prove the returned source actually works on real DOM —
+    // mocked `evaluate` tests in adapter specs only verify the script string
+    // contains expected tokens, but cannot catch silent matching bugs (cf.
+    // dianping #1312: mocked-evaluate single tests miss in-browser logic bugs).
+    function loadHelpers(tweetId, dom) {
+        const source = buildTwitterArticleScopeSource(tweetId);
+        const probe = new Function(
+            'document',
+            'window',
+            'URL',
+            `${source}\nreturn { findTargetArticle, __twHasLinkToTarget, __twGetStatusIdFromHref };`,
+        );
+        return probe(dom.window.document, dom.window, dom.window.URL);
+    }
+    function makeDom(html) {
+        return new JSDOM(`<html><body>${html}</body></html>`, { url: 'https://x.com/alice/status/2040254679301718161' });
+    }
+
+    it('finds the article whose link exactly matches the requested status id', () => {
+        const dom = makeDom(`
+            <article id="a"><a href="https://x.com/alice/status/2040254679301718161">link</a></article>
+            <article id="b"><a href="https://x.com/bob/status/9999999999999999999">link</a></article>
+        `);
+        const helpers = loadHelpers('2040254679301718161', dom);
+        const article = helpers.findTargetArticle();
+        expect(article?.id).toBe('a');
+    });
+
+    it('rejects substring matches — tweet id 123 must not match /status/1234567', () => {
+        // This is the codex-mini0 #1400 catch (substring vulnerability):
+        // `/status/123` was accepted as a substring of `/status/1234567`.
+        const dom = makeDom('<article><a href="https://x.com/alice/status/1234567">link</a></article>');
+        const helpers = loadHelpers('123', dom);
+        expect(helpers.findTargetArticle()).toBeUndefined();
+    });
+
+    it('rejects path-suffix attack — /status/<id>/photo/1 must not match status <id>', () => {
+        // Same regex anchor that parseTweetUrl uses — guards against attached
+        // paths like `/photo/1` that would otherwise pass with a loose suffix.
+        const dom = makeDom('<article><a href="https://x.com/alice/status/2040254679301718161/photo/1">link</a></article>');
+        const helpers = loadHelpers('2040254679301718161', dom);
+        expect(helpers.findTargetArticle()).toBeUndefined();
+    });
+
+    it('rejects off-domain links even when the path has the requested status id', () => {
+        const dom = makeDom('<article><a href="https://evil.com/alice/status/2040254679301718161">link</a></article>');
+        const helpers = loadHelpers('2040254679301718161', dom);
+        expect(helpers.findTargetArticle()).toBeUndefined();
+    });
+
+    it('rejects host-suffix and non-https status links', () => {
+        const dom = makeDom(`
+            <article id="suffix"><a href="https://x.com.evil.com/alice/status/2040254679301718161">link</a></article>
+            <article id="http"><a href="http://x.com/alice/status/2040254679301718161">link</a></article>
+        `);
+        const helpers = loadHelpers('2040254679301718161', dom);
+        expect(helpers.findTargetArticle()).toBeUndefined();
+    });
+
+    it('accepts exact Twitter/X status links with query and hash suffixes', () => {
+        const dom = makeDom('<article id="ok"><a href="https://mobile.twitter.com/alice/status/2040254679301718161?s=20#fragment">link</a></article>');
+        const helpers = loadHelpers('2040254679301718161', dom);
+        expect(helpers.findTargetArticle()?.id).toBe('ok');
+    });
+
+    it('matches /i/status/<id> URL form', () => {
+        const dom = makeDom('<article><a href="https://x.com/i/status/2040318731105313143">link</a></article>');
+        const helpers = loadHelpers('2040318731105313143', dom);
+        expect(helpers.findTargetArticle()).toBeTruthy();
+    });
+
+    it('__twHasLinkToTarget reports true on any descendant <a> matching tweet id', () => {
+        // Used by quote-card guard in quote.js — the quoted tweet card is not
+        // inside an <article>, but somewhere on the compose page.
+        const dom = makeDom(`
+            <div data-testid="card.wrapper">
+                <a href="https://x.com/alice/status/2040254679301718161">quoted card</a>
+            </div>
+        `);
+        const helpers = loadHelpers('2040254679301718161', dom);
+        expect(helpers.__twHasLinkToTarget(dom.window.document)).toBe(true);
+    });
+
+    it('__twGetStatusIdFromHref returns null on non-status URLs', () => {
+        const dom = makeDom('');
+        const helpers = loadHelpers('123', dom);
+        expect(helpers.__twGetStatusIdFromHref('https://x.com/alice/home')).toBeNull();
+        expect(helpers.__twGetStatusIdFromHref('https://x.com/alice/status/123/photo/1')).toBeNull();
+        expect(helpers.__twGetStatusIdFromHref('https://evil.com/alice/status/123')).toBeNull();
+        expect(helpers.__twGetStatusIdFromHref('https://x.com.evil.com/alice/status/123')).toBeNull();
+        expect(helpers.__twGetStatusIdFromHref('http://x.com/alice/status/123')).toBeNull();
+        expect(helpers.__twGetStatusIdFromHref('not a url')).toBeNull();
+    });
+
+    it('emits the canonical regex anchor — guards future maintainers from dropping ^ or $', () => {
+        const source = buildTwitterArticleScopeSource('123');
+        // Source-level assertion complements the JSDOM behavioural tests above.
+        // If a future refactor relaxes the anchor (e.g. drops ^ or $), the
+        // JSDOM tests would still pass on benign inputs but fail on adversarial
+        // cases. This token check ensures the regex shape itself is preserved.
+        expect(source).toContain('/^\\/(?:[^/]+|i)\\/status\\/(\\d+)\\/?$/');
+    });
+});
 
 describe('twitter extractMedia', () => {
     it('returns false + empty list when legacy has no media', () => {

package/clis/twitter/thread.js

@@ -1,8 +1,8 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { extractMedia } from './shared.js';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const TWEET_DETAIL_QUERY_ID = 'nBS-WpgA6ZG0CyNHD517JQ';
 const FEATURES = {
     responsive_web_graphql_exclude_directive_enabled: true,
@@ -101,8 +101,9 @@ cli({
     strategy: Strategy.COOKIE,
     browser: true,
     args: [
-        { name: 'tweet-id', positional: true, type: 'string', required: true },
+        { name: 'tweet-id', positional: true, type: 'string', required: true, help: 'Tweet numeric ID (e.g. 1234567890) or full status URL' },
         { name: 'limit', type: 'int', default: 50 },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the thread by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps the conversation\'s structural ordering.' },
     ],
     columns: ['id', 'author', 'text', 'likes', 'retweets', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
@@ -121,7 +122,7 @@ cli({
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         // Build auth headers in TypeScript
         const headers = JSON.stringify({
-            'Authorization': `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
+            'Authorization': `Bearer ${decodeURIComponent(TWITTER_BEARER_TOKEN)}`,
             'X-Csrf-Token': ct0,
             'X-Twitter-Auth-Type': 'OAuth2Session',
             'X-Twitter-Active-User': 'yes',
@@ -149,6 +150,7 @@ cli({
                 break;
             cursor = nextCursor;
         }
-        return allTweets.slice(0, kwargs.limit);
+        const trimmed = allTweets.slice(0, kwargs.limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     },
 });

package/clis/twitter/timeline.js

@@ -1,8 +1,8 @@
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { resolveTwitterQueryId, extractMedia } from './shared.js';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const HOME_TIMELINE_QUERY_ID = 'c-CzHF1LboFilMpsx4ZCrQ';
 const HOME_LATEST_TIMELINE_QUERY_ID = 'BKB7oi212Fi7kQtCBGE4zA';
 // Endpoint config: for-you uses GET HomeTimeline, following uses POST HomeLatestTimeline
@@ -137,7 +137,7 @@ cli({
     site: 'twitter',
     name: 'timeline',
     access: 'read',
-    description: 'Fetch Twitter timeline (for-you or following)',
+    description: 'Fetch the logged-in user\'s home timeline (for-you algorithmic feed by default; pass --type following for the chronological feed of accounts you follow)',
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
@@ -146,9 +146,10 @@ cli({
             name: 'type',
             default: 'for-you',
             choices: ['for-you', 'following'],
-            help: 'Timeline type: for-you (algorithmic) or following (chronological)',
+            help: 'Which home-timeline feed to read. Default for-you (algorithmic). Use following for the chronological feed of accounts you follow.',
         },
-        { name: 'limit', type: 'int', default: 20 },
+        { name: 'limit', type: 'int', default: 20, help: 'Maximum number of tweets to return (default 20).' },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the timeline 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', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
@@ -168,7 +169,7 @@ cli({
         const queryId = await resolveTwitterQueryId(page, endpoint, fallbackQueryId);
         // Build auth headers
         const headers = JSON.stringify({
-            Authorization: `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
+            Authorization: `Bearer ${decodeURIComponent(TWITTER_BEARER_TOKEN)}`,
             'X-Csrf-Token': ct0,
             'X-Twitter-Auth-Type': 'OAuth2Session',
             'X-Twitter-Active-User': 'yes',
@@ -196,7 +197,8 @@ cli({
                 break;
             cursor = nextCursor;
         }
-        return allTweets.slice(0, limit);
+        const trimmed = allTweets.slice(0, limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     },
 });
 export const __test__ = {

package/clis/twitter/tweets.js

@@ -1,8 +1,8 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { resolveTwitterQueryId, sanitizeQueryId, extractMedia } from './shared.js';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
 
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const USER_TWEETS_QUERY_ID = '6fWQaBPK51aGyC_VC7t9GQ';
 const USER_BY_SCREEN_NAME_QUERY_ID = 'IGgvgiOx4QZndDHuD3x9TQ';
 
@@ -152,6 +152,7 @@ cli({
     args: [
         { name: 'username', type: 'string', positional: true, required: true, help: 'Twitter screen name (with or without @)' },
         { name: 'limit', type: 'int', default: 20, help: 'Max tweets to return' },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the tweets by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps the chronological ordering.' },
     ],
     columns: ['id', 'author', 'created_at', 'is_retweet', 'text', 'likes', 'retweets', 'replies', 'views', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
@@ -171,7 +172,7 @@ cli({
         const userByScreenNameQueryId = await resolveTwitterQueryId(page, 'UserByScreenName', USER_BY_SCREEN_NAME_QUERY_ID);
 
         const headers = JSON.stringify({
-            'Authorization': `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
+            'Authorization': `Bearer ${decodeURIComponent(TWITTER_BEARER_TOKEN)}`,
             'X-Csrf-Token': ct0,
             'X-Twitter-Auth-Type': 'OAuth2Session',
             'X-Twitter-Active-User': 'yes',
@@ -207,7 +208,8 @@ cli({
         }
 
         if (all.length === 0) throw new EmptyResultError(`@${username} has no recent tweets`, 'Account may be private or suspended');
-        return all.slice(0, limit);
+        const trimmed = all.slice(0, limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     },
 });
 

package/clis/twitter/unbookmark.js

@@ -1,5 +1,7 @@
 import { CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseTweetUrl, buildTwitterArticleScopeSource } from './shared.js';
+
 cli({
     site: 'twitter',
     name: 'unbookmark',
@@ -15,21 +17,25 @@ cli({
     func: async (page, kwargs) => {
         if (!page)
             throw new CommandExecutionError('Browser session required for twitter unbookmark');
-        await page.goto(kwargs.url);
+        const target = parseTweetUrl(kwargs.url);
+        await page.goto(target.url);
         await page.wait({ selector: '[data-testid="primaryColumn"]' });
         const result = await page.evaluate(`(async () => {
         try {
+            ${buildTwitterArticleScopeSource(target.id)}
             let attempts = 0;
             let removeBtn = null;
+            let targetArticle = null;
 
             while (attempts < 20) {
-                // Check if not bookmarked
-                const bookmarkBtn = document.querySelector('[data-testid="bookmark"]');
+                targetArticle = findTargetArticle();
+                // Check if not bookmarked (already removed)
+                const bookmarkBtn = targetArticle?.querySelector('[data-testid="bookmark"]');
                 if (bookmarkBtn) {
                     return { ok: true, message: 'Tweet is not bookmarked (already removed).' };
                 }
 
-                removeBtn = document.querySelector('[data-testid="removeBookmark"]');
+                removeBtn = targetArticle?.querySelector('[data-testid="removeBookmark"]') || null;
                 if (removeBtn) break;
 
                 await new Promise(r => setTimeout(r, 500));
@@ -37,14 +43,15 @@ cli({
             }
 
             if (!removeBtn) {
-                return { ok: false, message: 'Could not find Remove Bookmark button. Are you logged in?' };
+                return { ok: false, message: 'Could not find Remove Bookmark button on the requested tweet. Are you logged in?' };
             }
 
             removeBtn.click();
             await new Promise(r => setTimeout(r, 1000));
 
             // Verify
-            const verify = document.querySelector('[data-testid="bookmark"]');
+            const verifyArticle = findTargetArticle() || targetArticle;
+            const verify = verifyArticle?.querySelector('[data-testid="bookmark"]');
             if (verify) {
                 return { ok: true, message: 'Tweet successfully removed from bookmarks.' };
             } else {

package/clis/twitter/unbookmark.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 './unbookmark.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter unbookmark command', () => {
+    it('navigates to the tweet URL and reports success when the unbookmark script confirms', async () => {
+        const cmd = getRegistry().get('twitter/unbookmark');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Tweet successfully removed from bookmarks.' },
+        ]);
+        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];
+        // Idempotency probe: when already not bookmarked ([data-testid="bookmark"] present),
+        // the script returns ok:true with an "already removed" message.
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"bookmark\"]')");
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"removeBookmark\"]')");
+        expect(script).toContain('removeBtn.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(result).toEqual([
+            { status: 'success', message: 'Tweet successfully removed from bookmarks.' },
+        ]);
+    });
+
+    it('returns a failed row without re-waiting when the unbookmark script reports a UI mismatch', async () => {
+        const cmd = getRegistry().get('twitter/unbookmark');
+        const page = createPageMock([
+            {
+                ok: false,
+                message: 'Could not find Remove Bookmark button on the requested tweet. Are you logged in?',
+            },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(result).toEqual([
+            {
+                status: 'failed',
+                message: 'Could not find Remove Bookmark button on the requested tweet. Are you logged in?',
+            },
+        ]);
+        expect(page.wait).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws CommandExecutionError when no page is provided', async () => {
+        const cmd = getRegistry().get('twitter/unbookmark');
+        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/unbookmark');
+        const page = createPageMock([]);
+        await expect(cmd.func(page, {
+            url: 'http://x.com/alice/status/2040254679301718161',
+        })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});

package/clis/twitter/unlike.js

@@ -0,0 +1,80 @@
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseTweetUrl, buildTwitterArticleScopeSource } from './shared.js';
+
+cli({
+    site: 'twitter',
+    name: 'unlike',
+    access: 'write',
+    description: 'Remove a like from a specific tweet',
+    domain: 'x.com',
+    strategy: Strategy.UI,
+    browser: true,
+    args: [
+        { name: 'url', type: 'string', required: true, positional: true, help: 'The URL of the tweet to unlike' },
+    ],
+    columns: ['status', 'message'],
+    func: async (page, kwargs) => {
+        if (!page)
+            throw new CommandExecutionError('Browser session required for twitter unlike');
+        const target = parseTweetUrl(kwargs.url);
+        await page.goto(target.url);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
+        const result = await page.evaluate(`(async () => {
+        try {
+            ${buildTwitterArticleScopeSource(target.id)}
+            // Poll for the tweet to render. State probes scoped to the article
+            // matching the requested status id — bare querySelector on a
+            // conversation page would silently grab the first article (e.g.
+            // the parent tweet) and unlike the wrong one.
+            let attempts = 0;
+            let likeBtn = null;
+            let unlikeBtn = null;
+            let targetArticle = null;
+
+            while (attempts < 20) {
+                targetArticle = findTargetArticle();
+                likeBtn = targetArticle?.querySelector('[data-testid="like"]') || null;
+                unlikeBtn = targetArticle?.querySelector('[data-testid="unlike"]') || null;
+
+                if (likeBtn || unlikeBtn) break;
+
+                await new Promise(r => setTimeout(r, 500));
+                attempts++;
+            }
+
+            // Check if it's already not liked
+            if (likeBtn) {
+                return { ok: true, message: 'Tweet is not liked (already unliked).' };
+            }
+
+            if (!unlikeBtn) {
+                return { ok: false, message: 'Could not find the Unlike button on this tweet after waiting 10 seconds. Are you logged in?' };
+            }
+
+            // Click Unlike
+            unlikeBtn.click();
+            await new Promise(r => setTimeout(r, 1000));
+
+            // Verify success by checking if the 'like' button reappeared
+            const verifyArticle = findTargetArticle() || targetArticle;
+            const verifyBtn = verifyArticle?.querySelector('[data-testid="like"]');
+            if (verifyBtn) {
+                return { ok: true, message: 'Tweet successfully unliked.' };
+            } else {
+                return { ok: false, message: 'Unlike action was initiated but UI did not update as expected.' };
+            }
+        } catch (e) {
+            return { ok: false, message: e.toString() };
+        }
+    })()`);
+        if (result.ok) {
+            // Wait for the unlike network request to be processed
+            await page.wait(2);
+        }
+        return [{
+                status: result.ok ? 'success' : 'failed',
+                message: result.message
+            }];
+    }
+});

package/clis/twitter/unlike.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './unlike.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter unlike command', () => {
+    it('navigates to the tweet URL and reports success when the unlike script confirms', async () => {
+        const cmd = getRegistry().get('twitter/unlike');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Tweet successfully unliked.' },
+        ]);
+        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"]' });
+        // After ok:true the adapter waits an extra 2s for the network round-trip.
+        expect(page.wait).toHaveBeenNthCalledWith(2, 2);
+        const script = page.evaluate.mock.calls[0][0];
+        // Idempotency check: looks for the like button (already-not-liked path) before clicking unlike.
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"like\"]')");
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"unlike\"]')");
+        expect(script).toContain('unlikeBtn.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(result).toEqual([
+            { status: 'success', message: 'Tweet successfully unliked.' },
+        ]);
+    });
+
+    it('returns a failed row without re-waiting when the unlike script reports a UI mismatch', async () => {
+        const cmd = getRegistry().get('twitter/unlike');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            {
+                ok: false,
+                message: 'Could not find the Unlike button on this tweet after waiting 10 seconds. Are you logged in?',
+            },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(result).toEqual([
+            {
+                status: 'failed',
+                message: 'Could not find the Unlike button on this tweet after waiting 10 seconds. Are you logged in?',
+            },
+        ]);
+        // Only the primaryColumn wait should run when ok is false.
+        expect(page.wait).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws CommandExecutionError when no page is provided', async () => {
+        const cmd = getRegistry().get('twitter/unlike');
+        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/unlike');
+        const page = createPageMock([]);
+        await expect(cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161/photo/1',
+        })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});