@jackwener/opencli 1.7.13 → 1.7.15

package/clis/twitter/hide-reply.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './hide-reply.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter hide-reply command', () => {
+    it('navigates to the reply URL and reports success when the hide-reply script confirms', async () => {
+        const cmd = getRegistry().get('twitter/hide-reply');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Reply successfully hidden.' },
+        ]);
+        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];
+        // Article-scoped More menu lookup — without scoping, the bare
+        // [aria-label="More"] selector grabs the parent tweet's More menu and
+        // silently hides the wrong reply (or fails because the parent is not a
+        // reply you authored).
+        expect(script).toContain('moreMenu.click()');
+        expect(script).toContain('[role="menuitem"]');
+        expect(script).toContain("'Hide reply'");
+        expect(script).toContain('hideItem.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: 'Reply successfully hidden.' },
+        ]);
+    });
+
+    it('returns a failed row without re-waiting when the hide-reply script reports a UI mismatch', async () => {
+        const cmd = getRegistry().get('twitter/hide-reply');
+        const page = createPageMock([
+            {
+                ok: false,
+                message: 'Could not find "Hide reply" option. This may not be a reply on your tweet.',
+            },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(result).toEqual([
+            {
+                status: 'failed',
+                message: 'Could not find "Hide reply" option. This may not be a reply on your tweet.',
+            },
+        ]);
+        expect(page.wait).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws CommandExecutionError when no page is provided', async () => {
+        const cmd = getRegistry().get('twitter/hide-reply');
+        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/hide-reply');
+        const page = createPageMock([]);
+        await expect(cmd.func(page, {
+            url: 'https://x.com.evil.com/alice/status/2040254679301718161',
+        })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});

package/clis/twitter/like.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: 'like',
@@ -15,21 +17,28 @@ cli({
     func: async (page, kwargs) => {
         if (!page)
             throw new CommandExecutionError('Browser session required for twitter like');
-        await page.goto(kwargs.url);
+        const target = parseTweetUrl(kwargs.url);
+        await page.goto(target.url);
         await page.wait({ selector: '[data-testid="primaryColumn"]' }); // Wait for tweet to load completely
         const result = await page.evaluate(`(async () => {
         try {
-            // Poll for the tweet to render
+            ${buildTwitterArticleScopeSource(target.id)}
+            // Poll for the tweet to render. We scope state probes to the
+            // article matching the requested status id — on conversation
+            // pages multiple articles render and a bare querySelector would
+            // grab the first one (silent: like the wrong tweet).
             let attempts = 0;
             let likeBtn = null;
             let unlikeBtn = null;
-            
+            let targetArticle = null;
+
             while (attempts < 20) {
-                unlikeBtn = document.querySelector('[data-testid="unlike"]');
-                likeBtn = document.querySelector('[data-testid="like"]');
-                
-                if (unlikeBtn || likeBtn) break;
-                
+                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++;
             }
@@ -46,9 +55,10 @@ cli({
             // Click Like
             likeBtn.click();
             await new Promise(r => setTimeout(r, 1000));
-            
-            // Verify success by checking if the 'unlike' button appeared
-            const verifyBtn = document.querySelector('[data-testid="unlike"]');
+
+            // Verify success by checking if the 'unlike' button reappeared
+            const verifyArticle = findTargetArticle() || targetArticle;
+            const verifyBtn = verifyArticle?.querySelector('[data-testid="unlike"]');
             if (verifyBtn) {
                 return { ok: true, message: 'Tweet successfully liked.' };
             } else {

package/clis/twitter/like.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 './like.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter like command', () => {
+    it('navigates to the tweet URL and reports success when the like script confirms', async () => {
+        const cmd = getRegistry().get('twitter/like');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Tweet successfully liked.' },
+        ]);
+        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: looks for the unlike button (already-liked path) before clicking.
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"like\"]')");
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"unlike\"]')");
+        expect(script).toContain('likeBtn.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 liked.' },
+        ]);
+    });
+
+    it('returns a failed row without re-waiting when the like script reports a UI mismatch', async () => {
+        const cmd = getRegistry().get('twitter/like');
+        const page = createPageMock([
+            {
+                ok: false,
+                message: 'Could not find the Like 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 Like 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/like');
+        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/like');
+        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();
+    });
+});

package/clis/twitter/likes.js

@@ -1,7 +1,7 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { resolveTwitterQueryId, sanitizeQueryId, extractMedia } from './shared.js';
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
 const LIKES_QUERY_ID = 'RozQdCp4CilQzrcuU0NY5w';
 const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
 const FEATURES = {
@@ -138,13 +138,14 @@ cli({
     site: 'twitter',
     name: 'likes',
     access: 'read',
-    description: 'Fetch liked tweets of a Twitter user',
+    description: 'Fetch liked tweets of a Twitter user (defaults to the logged-in user when no username is given)',
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
     args: [
-        { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (without @). Defaults to logged-in user.' },
-        { name: 'limit', type: 'int', default: 20 },
+        { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (with or without @). Defaults to the logged-in user when omitted.' },
+        { name: 'limit', type: 'int', default: 20, help: 'Maximum number of liked tweets to return (default 20).' },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the liked 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 API\'s native (recency) ordering.' },
     ],
     columns: ['id', 'author', 'name', 'text', 'likes', 'retweets', 'created_at', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
@@ -170,7 +171,7 @@ cli({
         const likesQueryId = await resolveTwitterQueryId(page, 'Likes', LIKES_QUERY_ID);
         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',
@@ -208,7 +209,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/list-add.js

@@ -2,8 +2,8 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { resolveTwitterQueryId } from './shared.js';
 import { parseListsManagement } from './lists.js';
+import { TWITTER_BEARER_TOKEN } from './utils.js';
 
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
 const LISTS_MANAGEMENT_QUERY_ID = '78UbkyXwXBD98IgUWXOy9g';
 
@@ -71,8 +71,8 @@ cli({
     strategy: Strategy.UI,
     browser: true,
     args: [
-        { name: 'listId', positional: true, type: 'string', required: true },
-        { name: 'username', positional: true, type: 'string', required: true },
+        { name: 'listId', positional: true, type: 'string', required: true, help: 'Numeric ID of the list you own (e.g. from `opencli twitter lists`)' },
+        { name: 'username', positional: true, type: 'string', required: true, help: 'Twitter/X handle to add (with or without @)' },
     ],
     columns: ['listId', 'username', 'userId', 'status', 'message'],
     func: async (page, kwargs) => {
@@ -94,7 +94,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',

package/clis/twitter/list-remove.js

@@ -2,8 +2,8 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { resolveTwitterQueryId } from './shared.js';
 import { parseListsManagement } from './lists.js';
+import { TWITTER_BEARER_TOKEN } from './utils.js';
 
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
 const LISTS_MANAGEMENT_QUERY_ID = '78UbkyXwXBD98IgUWXOy9g';
 
@@ -80,8 +80,8 @@ cli({
     strategy: Strategy.UI,
     browser: true,
     args: [
-        { name: 'listId', positional: true, type: 'string', required: true },
-        { name: 'username', positional: true, type: 'string', required: true },
+        { name: 'listId', positional: true, type: 'string', required: true, help: 'Numeric ID of the list you own (e.g. from `opencli twitter lists`)' },
+        { name: 'username', positional: true, type: 'string', required: true, help: 'Twitter/X handle to remove (with or without @)' },
     ],
     columns: ['listId', 'username', 'userId', 'status', 'message'],
     func: async (page, kwargs) => {
@@ -101,7 +101,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',

package/clis/twitter/list-tweets.js

@@ -1,7 +1,7 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
 
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const LIST_TWEETS_QUERY_ID = 'RlZzktZY_9wJynoepm8ZsA';
 const OPERATION_NAME = 'ListLatestTweetsTimeline';
 
@@ -113,8 +113,9 @@ cli({
     strategy: Strategy.COOKIE,
     browser: true,
     args: [
-        { name: 'listId', positional: true, type: 'string', required: true },
+        { name: 'listId', positional: true, type: 'string', required: true, help: 'Numeric ID of a Twitter/X list (e.g. from `opencli twitter lists`)' },
         { name: 'limit', type: 'int', default: 50 },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the list 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 the list\'s native (recency) ordering.' },
     ],
     columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'created_at', 'url'],
     func: async (page, kwargs) => {
@@ -155,7 +156,7 @@ cli({
             return null;
         }`) || LIST_TWEETS_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',
@@ -181,6 +182,7 @@ cli({
                 break;
             cursor = nextCursor;
         }
-        return allTweets.slice(0, limit);
+        const trimmed = allTweets.slice(0, limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     },
 });

package/clis/twitter/lists.js

@@ -1,7 +1,7 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { TWITTER_BEARER_TOKEN } from './utils.js';
 
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const LISTS_QUERY_ID = '78UbkyXwXBD98IgUWXOy9g';
 const OPERATION_NAME = 'ListsManagementPageTimeline';
 
@@ -93,7 +93,7 @@ export const command = cli({
     strategy: Strategy.COOKIE,
     browser: true,
     args: [
-        { name: 'limit', type: 'int', default: 50 },
+        { name: 'limit', type: 'int', default: 50, help: 'Maximum number of lists to return (default 50).' },
     ],
     columns: ['id', 'name', 'members', 'followers', 'mode'],
     func: async (page, kwargs) => {
@@ -130,7 +130,7 @@ export const command = cli({
             return null;
         }`) || LISTS_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',

package/clis/twitter/notifications.js

@@ -4,12 +4,12 @@ cli({
     site: 'twitter',
     name: 'notifications',
     access: 'read',
-    description: 'Get Twitter/X notifications',
+    description: 'Get your Twitter/X notifications (the logged-in user\'s likes/replies/follows feed, newest first)',
     domain: 'x.com',
     strategy: Strategy.INTERCEPT,
     browser: true,
     args: [
-        { name: 'limit', type: 'int', default: 20 },
+        { name: 'limit', type: 'int', default: 20, help: 'Maximum number of notifications to return (default 20).' },
     ],
     columns: ['id', 'action', 'author', 'text', 'url'],
     func: async (page, kwargs) => {

package/clis/twitter/profile.js

@@ -1,17 +1,18 @@
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { resolveTwitterQueryId } from './shared.js';
+import { TWITTER_BEARER_TOKEN } from './utils.js';
 const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
 cli({
     site: 'twitter',
     name: 'profile',
     access: 'read',
-    description: 'Fetch a Twitter user profile (bio, stats, etc.)',
+    description: 'Fetch a Twitter user profile — bio, stats, etc. (defaults to the logged-in user when no username is given)',
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
     args: [
-        { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (without @). Defaults to logged-in user.' },
+        { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (with or without @). Defaults to the logged-in user when omitted.' },
     ],
     columns: ['screen_name', 'name', 'bio', 'location', 'url', 'followers', 'following', 'tweets', 'likes', 'verified', 'created_at'],
     func: async (page, kwargs) => {
@@ -38,7 +39,7 @@ cli({
         const ct0 = document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1];
         if (!ct0) return {error: 'No ct0 cookie — not logged into x.com'};
 
-        const bearer = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+        const bearer = ${JSON.stringify(TWITTER_BEARER_TOKEN)};
         const headers = {
           'Authorization': 'Bearer ' + decodeURIComponent(bearer),
           'X-Csrf-Token': ct0,

package/clis/twitter/quote.js

@@ -0,0 +1,167 @@
+import * as fs from 'node:fs';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseTweetUrl, buildTwitterArticleScopeSource } from './shared.js';
+import {
+    COMPOSER_FILE_INPUT_SELECTOR,
+    attachComposerImage,
+    downloadRemoteImage,
+    resolveImagePath,
+} from './utils.js';
+
+function buildQuoteComposerUrl(url) {
+    // Twitter/X quote-tweet compose URL: the `url` param attaches the source
+    // tweet as a quoted card. Validating tweet-id shape early surfaces obvious
+    // typos before any browser interaction.
+    const parsed = parseTweetUrl(url);
+    return `https://x.com/compose/post?url=${encodeURIComponent(parsed.url)}`;
+}
+
+async function submitQuote(page, text, tweetId) {
+    return page.evaluate(`(async () => {
+        try {
+            ${buildTwitterArticleScopeSource(tweetId)}
+            const visible = (el) => !!el && (el.offsetParent !== null || el.getClientRects().length > 0);
+            const boxes = Array.from(document.querySelectorAll('[data-testid="tweetTextarea_0"]'));
+            const box = boxes.find(visible) || boxes[0];
+            if (!box) {
+                return { ok: false, message: 'Could not find the quote composer text area. Are you logged in?' };
+            }
+
+            box.focus();
+            const textToInsert = ${JSON.stringify(text)};
+            // execCommand('insertText') is more reliable with Twitter's Draft.js editor.
+            if (!document.execCommand('insertText', false, textToInsert)) {
+                // Fallback to paste event if execCommand fails.
+                const dataTransfer = new DataTransfer();
+                dataTransfer.setData('text/plain', textToInsert);
+                box.dispatchEvent(new ClipboardEvent('paste', {
+                    clipboardData: dataTransfer,
+                    bubbles: true,
+                    cancelable: true,
+                }));
+            }
+
+            await new Promise(r => setTimeout(r, 1000));
+
+            // Confirm the quoted card is rendered before submitting; otherwise
+            // we may accidentally post a plain tweet without the quote
+            // attachment. The compose page does not wrap the card in an
+            // <article>, so we probe the document for any link whose path
+            // exactly matches the requested status id (uses __twHasLinkToTarget
+            // from buildTwitterArticleScopeSource).
+            let cardAttempts = 0;
+            let hasQuoteCard = false;
+            while (cardAttempts < 20) {
+                hasQuoteCard = __twHasLinkToTarget(document);
+                if (hasQuoteCard) break;
+                await new Promise(r => setTimeout(r, 250));
+                cardAttempts++;
+            }
+            if (!hasQuoteCard) {
+                return { ok: false, message: 'Quote target did not render in the composer. The source tweet may be deleted or restricted.' };
+            }
+
+            const buttons = Array.from(
+                document.querySelectorAll('[data-testid="tweetButton"], [data-testid="tweetButtonInline"]')
+            );
+            const btn = buttons.find((el) => visible(el) && !el.disabled && el.getAttribute('aria-disabled') !== 'true');
+            if (!btn) {
+                return { ok: false, message: 'Tweet button is disabled or not found.' };
+            }
+
+            btn.click();
+
+            const normalize = s => String(s || '').replace(/\\u00a0/g, ' ').replace(/\\s+/g, ' ').trim();
+            const expectedText = normalize(textToInsert);
+            for (let i = 0; i < 30; i++) {
+                await new Promise(r => setTimeout(r, 500));
+                const toasts = Array.from(document.querySelectorAll('[role="alert"], [data-testid="toast"]'))
+                    .filter((el) => visible(el));
+                const successToast = toasts.find((el) => /sent|posted|your post was sent|your tweet was sent/i.test(el.textContent || ''));
+                if (successToast) return { ok: true, message: 'Quote tweet posted successfully.' };
+                const alert = toasts.find((el) => /failed|error|try again|not sent|could not/i.test(el.textContent || ''));
+                if (alert) return { ok: false, message: (alert.textContent || 'Quote tweet failed to post.').trim() };
+
+                const visibleBoxes = Array.from(document.querySelectorAll('[data-testid="tweetTextarea_0"]')).filter(visible);
+                const composerStillHasText = visibleBoxes.some((box) =>
+                    normalize(box.innerText || box.textContent || '').includes(expectedText)
+                );
+                if (!composerStillHasText) return { ok: true, message: 'Quote tweet posted successfully.' };
+            }
+            return { ok: false, message: 'Quote tweet submission did not complete before timeout.' };
+        } catch (e) {
+            return { ok: false, message: e.toString() };
+        }
+    })()`);
+}
+
+cli({
+    site: 'twitter',
+    name: 'quote',
+    access: 'write',
+    description: 'Quote-tweet a specific tweet with your own text, optionally with a local or remote image',
+    domain: 'x.com',
+    strategy: Strategy.UI,
+    browser: true,
+    args: [
+        { name: 'url', type: 'string', required: true, positional: true, help: 'The URL of the tweet to quote' },
+        { name: 'text', type: 'string', required: true, positional: true, help: 'The text content of your quote' },
+        { name: 'image', help: 'Optional local image path to attach to the quote tweet' },
+        { name: 'image-url', help: 'Optional remote image URL to download and attach to the quote tweet' },
+    ],
+    columns: ['status', 'message', 'text'],
+    func: async (page, kwargs) => {
+        if (!page)
+            throw new CommandExecutionError('Browser session required for twitter quote');
+        if (kwargs.image && kwargs['image-url']) {
+            throw new CommandExecutionError('Use either --image or --image-url, not both.');
+        }
+
+        // Validate URL (typed ArgumentError on malformed/off-domain inputs)
+        // before any browser interaction or remote image download.
+        const target = parseTweetUrl(kwargs.url);
+
+        let localImagePath;
+        let cleanupDir;
+        try {
+            if (kwargs.image) {
+                localImagePath = resolveImagePath(kwargs.image);
+            } else if (kwargs['image-url']) {
+                const downloaded = await downloadRemoteImage(kwargs['image-url']);
+                localImagePath = downloaded.absPath;
+                cleanupDir = downloaded.cleanupDir;
+            }
+
+            // Dedicated composer is more reliable than the inline quote-tweet button.
+            await page.goto(`https://x.com/compose/post?url=${encodeURIComponent(target.url)}`, { waitUntil: 'load', settleMs: 2500 });
+            await page.wait({ selector: '[data-testid="tweetTextarea_0"]', timeout: 15 });
+
+            if (localImagePath) {
+                await page.wait({ selector: COMPOSER_FILE_INPUT_SELECTOR, timeout: 20 });
+                await attachComposerImage(page, localImagePath);
+            }
+
+            const result = await submitQuote(page, kwargs.text, target.id);
+            if (result.ok) {
+                // Wait for network submission to complete
+                await page.wait(3);
+            }
+            return [{
+                    status: result.ok ? 'success' : 'failed',
+                    message: result.message,
+                    text: kwargs.text,
+                    ...(kwargs.image ? { image: kwargs.image } : {}),
+                    ...(kwargs['image-url'] ? { 'image-url': kwargs['image-url'] } : {}),
+                }];
+        } finally {
+            if (cleanupDir) {
+                fs.rmSync(cleanupDir, { recursive: true, force: true });
+            }
+        }
+    }
+});
+
+export const __test__ = {
+    buildQuoteComposerUrl,
+};