@jackwener/opencli 1.7.13 → 1.7.14

package/clis/twitter/unlike.js

@@ -0,0 +1,87 @@
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseTweetUrl } 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 {
+            const tweetId = ${JSON.stringify(target.id)};
+            const findTargetArticle = () => Array.from(document.querySelectorAll('article')).find((article) =>
+                Array.from(article.querySelectorAll('a[href*="/status/"]')).some((link) => {
+                    try {
+                        const match = new URL(link.href, window.location.origin).pathname.match(/^\/(?:[^/]+|i)\/status\/(\d+)\/?$/);
+                        return match?.[1] === tweetId;
+                    } catch {
+                        return false;
+                    }
+                })
+            );
+            // Poll for the tweet to render
+            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,72 @@
+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()');
+        expect(script).toContain("document.querySelectorAll('article')");
+        expect(script).toContain('match?.[1] === tweetId');
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"unlike\"]')");
+        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();
+    });
+});

package/clis/twitter/unretweet.js

@@ -0,0 +1,99 @@
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseTweetUrl } from './shared.js';
+
+cli({
+    site: 'twitter',
+    name: 'unretweet',
+    access: 'write',
+    description: 'Undo a retweet on 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 unretweet' },
+    ],
+    columns: ['status', 'message'],
+    func: async (page, kwargs) => {
+        if (!page)
+            throw new CommandExecutionError('Browser session required for twitter unretweet');
+        const target = parseTweetUrl(kwargs.url);
+        await page.goto(target.url);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
+        const result = await page.evaluate(`(async () => {
+        try {
+            const tweetId = ${JSON.stringify(target.id)};
+            const findTargetArticle = () => Array.from(document.querySelectorAll('article')).find((article) =>
+                Array.from(article.querySelectorAll('a[href*="/status/"]')).some((link) => {
+                    try {
+                        const match = new URL(link.href, window.location.origin).pathname.match(/^\/(?:[^/]+|i)\/status\/(\d+)\/?$/);
+                        return match?.[1] === tweetId;
+                    } catch {
+                        return false;
+                    }
+                })
+            );
+            // Poll for the tweet to render
+            let attempts = 0;
+            let retweetBtn = null;
+            let unretweetBtn = null;
+            let targetArticle = null;
+
+            while (attempts < 20) {
+                targetArticle = findTargetArticle();
+                retweetBtn = targetArticle?.querySelector('[data-testid="retweet"]') || null;
+                unretweetBtn = targetArticle?.querySelector('[data-testid="unretweet"]') || null;
+
+                if (retweetBtn || unretweetBtn) break;
+
+                await new Promise(r => setTimeout(r, 500));
+                attempts++;
+            }
+
+            // Already not retweeted: idempotent success
+            if (retweetBtn) {
+                return { ok: true, message: 'Tweet is not retweeted (already removed).' };
+            }
+
+            if (!unretweetBtn) {
+                return { ok: false, message: 'Could not find the Unretweet button on this tweet after waiting 10 seconds. Are you logged in?' };
+            }
+
+            // Step 1: click Unretweet button → opens menu
+            unretweetBtn.click();
+
+            // Step 2: wait for the confirm menu item to appear, then click it
+            let confirmBtn = null;
+            for (let i = 0; i < 20; i++) {
+                await new Promise(r => setTimeout(r, 250));
+                confirmBtn = document.querySelector('[data-testid="unretweetConfirm"]');
+                if (confirmBtn) break;
+            }
+            if (!confirmBtn) {
+                return { ok: false, message: 'Unretweet menu opened but the confirm option did not appear.' };
+            }
+            confirmBtn.click();
+            await new Promise(r => setTimeout(r, 1000));
+
+            // Verify success by checking if the 'retweet' button reappeared
+            const verifyArticle = findTargetArticle() || targetArticle;
+            const verifyBtn = verifyArticle?.querySelector('[data-testid="retweet"]');
+            if (verifyBtn) {
+                return { ok: true, message: 'Tweet successfully unretweeted.' };
+            } else {
+                return { ok: false, message: 'Unretweet action was initiated but UI did not update as expected.' };
+            }
+        } catch (e) {
+            return { ok: false, message: e.toString() };
+        }
+    })()`);
+        if (result.ok) {
+            // Wait for the unretweet network request to be processed
+            await page.wait(2);
+        }
+        return [{
+                status: result.ok ? 'success' : 'failed',
+                message: result.message
+            }];
+    }
+});

package/clis/twitter/unretweet.test.js

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './unretweet.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter unretweet command', () => {
+    it('clicks the unretweet button then the confirm menu item and reports success', async () => {
+        const cmd = getRegistry().get('twitter/unretweet');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Tweet successfully unretweeted.' },
+        ]);
+        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 unretweet button
+        //   2) wait for and click the confirm menu item (data-testid="unretweetConfirm")
+        expect(script).toContain('unretweetBtn.click()');
+        expect(script).toContain("document.querySelector('[data-testid=\"unretweetConfirm\"]')");
+        expect(script).toContain('confirmBtn.click()');
+        expect(script).toContain("document.querySelectorAll('article')");
+        expect(script).toContain('match?.[1] === tweetId');
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"unretweet\"]')");
+        // Idempotency probe: when already not retweeted ([data-testid="retweet"] present),
+        // the script returns ok:true with an "already removed" message.
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"retweet\"]')");
+        expect(result).toEqual([
+            { status: 'success', message: 'Tweet successfully unretweeted.' },
+        ]);
+    });
+
+    it('returns a failed row when the confirm menu item never appears', async () => {
+        const cmd = getRegistry().get('twitter/unretweet');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: false, message: 'Unretweet 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: 'Unretweet 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/unretweet');
+        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/unretweet');
+        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/dist/src/browser/bridge.js

@@ -54,62 +54,64 @@ export class BrowserBridge {
         const effectiveSeconds = (timeoutSeconds && timeoutSeconds > 0) ? timeoutSeconds : Math.ceil(DAEMON_SPAWN_TIMEOUT / 1000);
         const timeoutMs = effectiveSeconds * 1000;
         const health = await getDaemonHealth({ contextId });
+        // Detect stale daemon before any fast path. A stale daemon can still have
+        // the extension connected, so this cannot live only in the no-extension branch.
+        const daemonVersion = health.status?.daemonVersion;
+        const isStale = !!health.status && (!daemonVersion || daemonVersion !== PKG_VERSION);
+        let staleDaemonReplaced = false;
+        if (isStale) {
+            // Stale daemon — restart it so all browser commands run against the
+            // currently installed package code, not the old daemon binary.
+            const reason = daemonVersion
+                ? `v${daemonVersion} ≠ v${PKG_VERSION}`
+                : `pre-version daemon, CLI is v${PKG_VERSION}`;
+            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
+            }
+            const shutdownAccepted = await requestDaemonShutdown();
+            const portReleased = shutdownAccepted && await waitForDaemonStop(3000);
+            if (!portReleased) {
+                // Stale daemon replacement failed — don't blindly spawn on an occupied port
+                throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down.\n` +
+                    '  Run manually: opencli daemon stop && opencli doctor', 'daemon-not-running');
+            }
+            // Port released — fall through to spawn a fresh daemon
+            staleDaemonReplaced = true;
+        }
         // Fast path: everything ready
-        if (health.state === 'ready')
+        if (!staleDaemonReplaced && health.state === 'ready')
             return;
-        if (health.state === 'profile-required') {
+        if (!staleDaemonReplaced && health.state === 'profile-required') {
             throw new BrowserConnectError('Multiple Browser Bridge profiles are connected', 'Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.\n' +
                 'Run opencli profile list to see connected profiles.', 'profile-required');
         }
-        if (health.state === 'profile-disconnected') {
+        if (!staleDaemonReplaced && health.state === 'profile-disconnected') {
             const label = contextId ?? health.status.contextId ?? 'unknown';
             throw new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 'profile-disconnected');
         }
         // Daemon running but no extension
-        if (health.state === 'no-extension') {
-            // Detect stale daemon: version mismatch OR missing daemonVersion (pre-version daemon)
-            const daemonVersion = health.status?.daemonVersion;
-            const isStale = !daemonVersion || daemonVersion !== PKG_VERSION;
-            if (isStale) {
-                // Stale daemon — restart it so extension gets a fresh WebSocket endpoint
-                const reason = daemonVersion
-                    ? `v${daemonVersion} ≠ v${PKG_VERSION}`
-                    : `pre-version daemon, CLI is v${PKG_VERSION}`;
-                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
-                    process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
-                }
-                const shutdownAccepted = await requestDaemonShutdown();
-                const portReleased = shutdownAccepted && await waitForDaemonStop(3000);
-                if (!portReleased) {
-                    // Stale daemon replacement failed — don't blindly spawn on an occupied port
-                    throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down.\n` +
-                        '  Run manually: opencli daemon stop && opencli doctor', 'daemon-not-running');
-                }
-                // Port released — fall through to spawn a fresh daemon
+        if (!staleDaemonReplaced && health.state === 'no-extension') {
+            // Same version — wait for extension to connect
+            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
+                process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
             }
-            else {
-                // Same version — wait for extension to connect
-                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
-                    process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
-                    process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
-                }
-                if (await this._pollUntilReady(timeoutMs, contextId))
-                    return;
-                const finalHealth = await getDaemonHealth({ contextId });
-                if (finalHealth.state === 'profile-required') {
-                    throw new BrowserConnectError('Multiple Browser Bridge profiles are connected', 'Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.\n' +
-                        'Run opencli profile list to see connected profiles.', 'profile-required');
-                }
-                if (finalHealth.state === 'profile-disconnected') {
-                    const label = contextId ?? finalHealth.status.contextId ?? 'unknown';
-                    throw new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 'profile-disconnected');
-                }
-                throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
-                    'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
-                    'If not installed:\n' +
-                    '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                    '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
+            if (await this._pollUntilReady(timeoutMs, contextId))
+                return;
+            const finalHealth = await getDaemonHealth({ contextId });
+            if (finalHealth.state === 'profile-required') {
+                throw new BrowserConnectError('Multiple Browser Bridge profiles are connected', 'Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.\n' +
+                    'Run opencli profile list to see connected profiles.', 'profile-required');
             }
+            if (finalHealth.state === 'profile-disconnected') {
+                const label = contextId ?? finalHealth.status.contextId ?? 'unknown';
+                throw new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 'profile-disconnected');
+            }
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
+                'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
+                'If not installed:\n' +
+                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
         }
         // No daemon — spawn one
         if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {

package/dist/src/browser.test.js

@@ -165,6 +165,24 @@ describe('BrowserBridge state', () => {
         const bridge = new BrowserBridge();
         await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Stale daemon could not be replaced');
     });
+    it('attempts stale daemon replacement even when extension is connected', async () => {
+        vi.spyOn(daemonClient, 'getDaemonHealth').mockResolvedValue({
+            state: 'ready',
+            status: {
+                ok: true,
+                pid: 1,
+                uptime: 0,
+                daemonVersion: '0.0.1',
+                extensionConnected: true,
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        vi.spyOn(daemonClient, 'requestDaemonShutdown').mockResolvedValue(false);
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Stale daemon could not be replaced');
+    });
 });
 describe('stealth anti-detection', () => {
     it('generates non-empty JS string', () => {

package/dist/src/cli.test.js

@@ -223,6 +223,7 @@ describe('createProgram root help descriptions', () => {
                 strategy: Strategy.PUBLIC,
                 browser: false,
                 args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+                columns: ['title', 'url'],
             });
             const program = createProgram('', '');
             const site = program.commands.find(cmd => cmd.name() === 'bilibili');
@@ -235,10 +236,99 @@ describe('createProgram root help descriptions', () => {
                     name: 'hot',
                     access: 'read',
                     description: 'Bilibili hot videos',
+                    browser: false,
                     example: 'opencli bilibili hot -f yaml',
-                    args: [{ name: 'limit', type: 'int', default: 20 }],
+                    command_options: [{ name: 'limit', type: 'int', default: 20 }],
+                    columns: ['title', 'url'],
                 },
             ]);
+            expect(data.commands[0]).not.toHaveProperty('args');
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('renders per-site text help without per-command common option noise', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+            });
+            cli({
+                site: 'bilibili',
+                name: 'video',
+                access: 'read',
+                description: 'Read one video',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: true,
+                args: [{ name: 'bvid', positional: true, required: true, help: 'Video id' }],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            expect(site).toBeTruthy();
+            const help = site.helpInformation();
+            expect(help).toContain('hot [options]  [read] Bilibili hot videos');
+            expect(help).toContain('video <bvid>   [read] Read one video');
+            expect(help).toContain('hot [options]');
+            expect(help).not.toContain('video <bvid> [options]');
+            expect(help).not.toContain('\nOptions:');
+            expect(help).toContain('Common options:');
+            expect(help).toContain('-f, --format <fmt>');
+            expect(help).toContain('--trace <mode>');
+            expect(help).toContain('get all command args/options in one structured response');
+        }
+        finally {
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('separates command args from common options in structured help', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        const argv = process.argv;
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'video',
+                access: 'read',
+                description: 'Read one video',
+                strategy: Strategy.PUBLIC,
+                domain: 'www.bilibili.com',
+                browser: true,
+                args: [
+                    { name: 'bvid', positional: true, required: true, help: 'Video id' },
+                    { name: 'with-comments', type: 'boolean', default: false, help: 'Include comments' },
+                ],
+                columns: ['title', 'url'],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            const command = site.commands.find(cmd => cmd.name() === 'video');
+            expect(command).toBeTruthy();
+            process.argv = ['node', 'opencli', 'bilibili', 'video', '--help', '-f', 'yaml'];
+            const data = yaml.load(command.helpInformation());
+            expect(data.usage).toBe('opencli bilibili video <bvid> [options]');
+            expect(data.browser).toBe(true);
+            expect(data.domain).toBe('www.bilibili.com');
+            expect(data.positionals).toMatchObject([{ name: 'bvid', positional: true, required: true }]);
+            expect(data.command_options).toMatchObject([{ name: 'with-comments', default: false }]);
+            expect(data.common_options.map((option) => option.name)).toEqual(['format', 'trace', 'verbose', 'help']);
+            expect(data.columns).toEqual(['title', 'url']);
+            expect(data).not.toHaveProperty('args');
         }
         finally {
             process.argv = argv;

package/dist/src/commanderAdapter.js

@@ -12,10 +12,9 @@
 import { log } from './logger.js';
 import yaml from 'js-yaml';
 import { fullName, getRegistry } from './registry.js';
-import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand, prepareCommandArgs } from './execution.js';
-import { commandHelpData, formatSiteCommandDescription, installStructuredHelp, siteHelpData, } from './help.js';
+import { commandHelpData, formatCommandHelpText, formatCommandListTerm, formatSiteCommandDescription, formatSiteHelpText, getRequestedHelpFormat, renderStructuredHelp, siteHelpData, } from './help.js';
 import { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
 /**
  * Register a single CliCommand as a Commander subcommand.
@@ -49,7 +48,16 @@ export function registerCommandToProgram(siteCmd, cmd) {
         .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
         .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
         .option('-v, --verbose', 'Debug output', false);
-    installStructuredHelp(subCmd, () => commandHelpData(cmd), () => formatRegistryHelpText(cmd));
+    const originalHelpInformation = subCmd.helpInformation.bind(subCmd);
+    subCmd.helpInformation = ((contextOptions) => {
+        const format = getRequestedHelpFormat();
+        if (format)
+            return renderStructuredHelp(commandHelpData(cmd), format);
+        // Keep a fallback reference so future Commander upgrades still initialize
+        // internal help state before we render the cleaner grouped command help.
+        void originalHelpInformation(contextOptions);
+        return formatCommandHelpText(cmd);
+    });
     subCmd.action(async (...actionArgs) => {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
         const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
@@ -174,7 +182,18 @@ export function registerAllCommands(program, siteGroups) {
         for (const cmd of commands) {
             registerCommandToProgram(siteCmd, cmd);
         }
-        installStructuredHelp(siteCmd, () => siteHelpData(site, commands));
+        const commandTerms = new Map(commands.map(cmd => [cmd.name, formatCommandListTerm(cmd)]));
+        siteCmd.configureHelp({
+            subcommandTerm: command => commandTerms.get(command.name()) ?? command.name(),
+        });
+        const originalSiteHelpInformation = siteCmd.helpInformation.bind(siteCmd);
+        siteCmd.helpInformation = ((contextOptions) => {
+            const format = getRequestedHelpFormat();
+            if (format)
+                return renderStructuredHelp(siteHelpData(site, commands), format);
+            void originalSiteHelpInformation(contextOptions);
+            return formatSiteHelpText(site, commands);
+        });
     }
     return [...commandsBySite.keys()].sort((a, b) => a.localeCompare(b));
 }

package/dist/src/help.d.ts

@@ -29,8 +29,12 @@ export interface RootAdapterGroups {
     sites: readonly string[];
 }
 export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+export declare function formatCommandListTerm(cmd: CliCommand): string;
 export declare function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown>;
 export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;
 export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
+export declare function formatCommonOptionsHelpText(): string;
+export declare function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string;
+export declare function formatCommandHelpText(cmd: CliCommand): string;
 export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;
 export declare function formatSiteCommandDescription(cmd: CliCommand): string;