@jackwener/opencli 1.7.19 → 1.7.20

package/clis/twitter/bookmarks.test.js

@@ -0,0 +1,205 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './bookmarks.js';
+
+const { parseBookmarks, extractBookmarkTweet } = __test__;
+
+describe('twitter bookmarks parser', () => {
+    it('extracts a baseline tweet with no media (has_media false, media_urls empty)', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '1',
+            legacy: {
+                full_text: 'plain bookmark',
+                favorite_count: 5,
+                retweet_count: 1,
+                bookmark_count: 2,
+                created_at: 'Wed Apr 16 10:00:00 +0000 2026',
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'alice', name: 'Alice' } } } },
+        }, new Set());
+        expect(tweet).toEqual({
+            id: '1',
+            author: 'alice',
+            name: 'Alice',
+            text: 'plain bookmark',
+            likes: 5,
+            retweets: 1,
+            bookmarks: 2,
+            created_at: 'Wed Apr 16 10:00:00 +0000 2026',
+            url: 'https://x.com/alice/status/1',
+            has_media: false,
+            media_urls: [],
+        });
+    });
+
+    it('includes photo media URLs from extended_entities', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '101',
+            legacy: {
+                full_text: 'pic bookmark',
+                extended_entities: {
+                    media: [
+                        { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/abc.jpg' },
+                        { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/def.jpg' },
+                    ],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'bob' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls).toEqual([
+            'https://pbs.twimg.com/media/abc.jpg',
+            'https://pbs.twimg.com/media/def.jpg',
+        ]);
+    });
+
+    it('extracts mp4 variant URL for video media', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '102',
+            legacy: {
+                full_text: 'video bookmark',
+                extended_entities: {
+                    media: [{
+                        type: 'video',
+                        media_url_https: 'https://pbs.twimg.com/amplify_video_thumb/thumb.jpg',
+                        video_info: {
+                            variants: [
+                                { content_type: 'application/x-mpegURL', url: 'https://video.twimg.com/playlist.m3u8' },
+                                { content_type: 'video/mp4', bitrate: 832000, url: 'https://video.twimg.com/low.mp4' },
+                                { content_type: 'video/mp4', bitrate: 2176000, url: 'https://video.twimg.com/high.mp4' },
+                            ],
+                        },
+                    }],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'carol' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls?.[0]).toMatch(/\.mp4$/);
+    });
+
+    it('falls back to entities.media when extended_entities is absent', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '103',
+            legacy: {
+                full_text: 'entities-only media',
+                entities: {
+                    media: [{ type: 'photo', media_url_https: 'https://pbs.twimg.com/media/legacy.jpg' }],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'dave' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls).toEqual(['https://pbs.twimg.com/media/legacy.jpg']);
+    });
+
+    it('prefers note_tweet text over truncated full_text', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '2',
+            legacy: { full_text: 'short text…', favorite_count: 0, retweet_count: 0, bookmark_count: 0 },
+            note_tweet: { note_tweet_results: { result: { text: 'full long-form text body' } } },
+            core: { user_results: { result: { core: { screen_name: 'erin' } } } },
+        }, new Set());
+        expect(tweet?.text).toBe('full long-form text body');
+    });
+
+    it('deduplicates tweets across the seen Set', () => {
+        const data = {
+            data: {
+                bookmark_timeline_v2: {
+                    timeline: {
+                        instructions: [{
+                            entries: [
+                                {
+                                    entryId: 'tweet-3',
+                                    content: {
+                                        itemContent: {
+                                            tweet_results: {
+                                                result: {
+                                                    rest_id: '3',
+                                                    legacy: { full_text: 'first', favorite_count: 0, retweet_count: 0, bookmark_count: 0 },
+                                                    core: { user_results: { result: { legacy: { screen_name: 'frank' } } } },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                                {
+                                    entryId: 'tweet-3-dup',
+                                    content: {
+                                        itemContent: {
+                                            tweet_results: {
+                                                result: {
+                                                    rest_id: '3',
+                                                    legacy: { full_text: 'duplicate' },
+                                                    core: { user_results: { result: { legacy: { screen_name: 'frank' } } } },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            ],
+                        }],
+                    },
+                },
+            },
+        };
+        const seen = new Set();
+        const { tweets } = parseBookmarks(data, seen);
+        expect(tweets).toHaveLength(1);
+        expect(tweets[0].text).toBe('first');
+    });
+
+    it('extracts cursor + tweets from the bookmark_timeline_v2 envelope', () => {
+        const data = {
+            data: {
+                bookmark_timeline_v2: {
+                    timeline: {
+                        instructions: [
+                            {
+                                type: 'TimelineAddEntries',
+                                entries: [
+                                    {
+                                        entryId: 'tweet-4',
+                                        content: {
+                                            itemContent: {
+                                                tweet_results: {
+                                                    result: {
+                                                        rest_id: '4',
+                                                        legacy: {
+                                                            full_text: 'envelope tweet',
+                                                            favorite_count: 1,
+                                                            retweet_count: 0,
+                                                            bookmark_count: 0,
+                                                            extended_entities: {
+                                                                media: [{ type: 'photo', media_url_https: 'https://pbs.twimg.com/media/x.jpg' }],
+                                                            },
+                                                        },
+                                                        core: { user_results: { result: { legacy: { screen_name: 'gina' } } } },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                    {
+                                        entryId: 'cursor-bottom-Y',
+                                        content: { __typename: 'TimelineTimelineCursor', cursorType: 'Bottom', value: 'NEXT' },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                },
+            },
+        };
+        const { tweets, nextCursor } = parseBookmarks(data, new Set());
+        expect(tweets).toHaveLength(1);
+        expect(tweets[0].id).toBe('4');
+        expect(tweets[0].has_media).toBe(true);
+        expect(tweets[0].media_urls).toEqual(['https://pbs.twimg.com/media/x.jpg']);
+        expect(nextCursor).toBe('NEXT');
+    });
+
+    it('returns empty tweets + null cursor for unknown envelope', () => {
+        expect(parseBookmarks({}, new Set())).toEqual({ tweets: [], nextCursor: null });
+    });
+});

package/dist/src/browser/daemon-client.d.ts

@@ -73,6 +73,7 @@ export interface DaemonStatus {
     profileDisconnected?: boolean;
     profiles?: BrowserProfileStatus[];
     pending: number;
+    commandResultUnknown?: number;
     memoryMB: number;
     port: number;
 }

package/dist/src/browser/daemon-client.js

@@ -105,6 +105,9 @@ async function sendCommandRaw(action, params) {
             });
             const result = (await res.json());
             if (!result.ok) {
+                if (result.errorCode === 'command_result_unknown') {
+                    throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
+                }
                 const isDuplicateCommandId = res.status === 409
                     || (result.error ?? '').includes('Duplicate command id');
                 if (isDuplicateCommandId && attempt < maxRetries) {

package/dist/src/browser/daemon-client.test.js

@@ -176,4 +176,24 @@ describe('daemon-client', () => {
         });
         expect(ids[0]).not.toBe(ids[1]);
     });
+    it('sendCommand does not retry command_result_unknown even when the message looks transient', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValue({
+            ok: false,
+            status: 503,
+            json: () => Promise.resolve({
+                id: 'server',
+                ok: false,
+                errorCode: 'command_result_unknown',
+                error: 'Extension disconnected after command timeout',
+                errorHint: 'Inspect state before retrying.',
+            }),
+        });
+        await expect(sendCommand('exec', { code: 'window.__mutate = true' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
+            hint: 'Inspect state before retrying.',
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
 });

package/dist/src/cli.js

@@ -15,7 +15,7 @@ import { serializeCommand, formatArgSummary } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
-import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
+import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
 import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
@@ -3005,6 +3005,7 @@ cli({
         .action((opts) => {
         const rows = loadExternalClis().map((ext) => ({
             name: ext.name,
+            package: ext.package ?? '',
             binary: ext.binary,
             installed: isBinaryInstalled(ext.binary),
             description: ext.description ?? '',
@@ -3013,7 +3014,7 @@ cli({
         }));
         renderOutput(rows, {
             fmt: opts.format,
-            columns: ['name', 'binary', 'installed', 'description', 'homepage', 'tags'],
+            columns: ['name', 'package', 'binary', 'installed', 'description', 'homepage', 'tags'],
             title: 'opencli/external/list',
             source: 'opencli external list',
         });
@@ -3067,6 +3068,10 @@ cli({
     // Classification derives from each adapter's `domain` field — see classifyAdapter.
     // External CLIs are taken from the externalClis registry (passthrough binaries).
     const externalNames = externalClis.map(ext => ext.name);
+    const externalHelpEntries = externalClis.map(ext => ({
+        name: ext.name,
+        label: formatExternalCliLabel(ext),
+    }));
     const siteDomains = new Map();
     for (const [, cmd] of getRegistry()) {
         if (!siteDomains.has(cmd.site))
@@ -3080,7 +3085,7 @@ cli({
         else
             sites.push(site);
     }
-    const adapterGroups = { external: externalNames, apps, sites };
+    const adapterGroups = { external: externalHelpEntries, apps, sites };
     const adapterNameSet = new Set([...externalNames, ...siteNames]);
     installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
     installCommanderNamespaceStructuredHelp(daemonCmd, { globalCommand: program, description: originalDaemonDescription });

package/dist/src/cli.test.js

@@ -168,6 +168,7 @@ describe('createProgram root help descriptions', () => {
             expect(data.site_adapters.sites).toEqual(['bilibili']);
             expect(data.external_clis.count).toBeGreaterThanOrEqual(0);
             expect(Array.isArray(data.external_clis.clis)).toBe(true);
+            expect(Array.isArray(data.external_clis.display)).toBe(true);
             // Adapters must NOT leak into the core commands list
             const commandNames = data.commands.map((cmd) => cmd.name);
             expect(commandNames).not.toContain('bilibili');

package/dist/src/daemon-utils.d.ts

@@ -0,0 +1,18 @@
+export declare const COMMAND_RESULT_UNKNOWN_CODE = "command_result_unknown";
+export declare const COMMAND_RESULT_UNKNOWN_HINT = "Inspect the browser/session state before retrying. Do not blindly retry write commands such as navigate, click, type, or eval.";
+export declare const PROFILE_DISCONNECTED_HINT = "Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.";
+export type DaemonFailureContract = {
+    message: string;
+    errorCode: string;
+    errorHint: string;
+    status: number;
+    countAsCommandResultUnknown: boolean;
+};
+export declare function commandResultUnknownMessage(action: string): string;
+export declare function buildExtensionDisconnectFailure(input: {
+    contextId: string;
+    action: string;
+    dispatched: boolean;
+}): DaemonFailureContract;
+export declare function buildCommandDispatchFailure(contextId: string): DaemonFailureContract;
+export declare function getResponseCorsHeaders(pathname: string, origin?: string): Record<string, string> | undefined;

package/dist/src/daemon-utils.js

@@ -0,0 +1,37 @@
+export const COMMAND_RESULT_UNKNOWN_CODE = 'command_result_unknown';
+export const COMMAND_RESULT_UNKNOWN_HINT = 'Inspect the browser/session state before retrying. Do not blindly retry write commands such as navigate, click, type, or eval.';
+export const PROFILE_DISCONNECTED_HINT = 'Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.';
+export function commandResultUnknownMessage(action) {
+    return `Browser connection dropped after the ${action} command was dispatched; it may have completed.`;
+}
+export function buildExtensionDisconnectFailure(input) {
+    if (input.dispatched) {
+        return {
+            message: commandResultUnknownMessage(input.action),
+            errorCode: COMMAND_RESULT_UNKNOWN_CODE,
+            errorHint: COMMAND_RESULT_UNKNOWN_HINT,
+            status: 503,
+            countAsCommandResultUnknown: true,
+        };
+    }
+    return buildCommandDispatchFailure(input.contextId);
+}
+export function buildCommandDispatchFailure(contextId) {
+    return {
+        message: `Browser profile "${contextId}" disconnected before command dispatch`,
+        errorCode: 'profile_disconnected',
+        errorHint: PROFILE_DISCONNECTED_HINT,
+        status: 503,
+        countAsCommandResultUnknown: false,
+    };
+}
+export function getResponseCorsHeaders(pathname, origin) {
+    if (pathname !== '/ping')
+        return undefined;
+    if (!origin || !origin.startsWith('chrome-extension://'))
+        return undefined;
+    return {
+        'Access-Control-Allow-Origin': origin,
+        Vary: 'Origin',
+    };
+}

package/dist/src/daemon.d.ts

@@ -19,4 +19,4 @@
  *   - Persistent — stays alive until explicit shutdown, SIGTERM, or uninstall
  *   - Listens on localhost:19825
  */
-export declare function getResponseCorsHeaders(pathname: string, origin?: string): Record<string, string> | undefined;
+export {};

package/dist/src/daemon.js

@@ -27,9 +27,11 @@ import { log } from './logger.js';
 import { PKG_VERSION } from './version.js';
 import { DEFAULT_CONTEXT_ID } from './browser/profile.js';
 import { recordExtensionVersion } from './update-check.js';
+import { buildCommandDispatchFailure, buildExtensionDisconnectFailure, getResponseCorsHeaders, } from './daemon-utils.js';
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const extensionProfiles = new Map();
 const pending = new Map();
+let commandResultUnknownCount = 0;
 const LOG_BUFFER_SIZE = 200;
 const logBuffer = [];
 class DaemonCommandFailure extends Error {
@@ -110,7 +112,16 @@ function unregisterExtensionConnection(ws) {
             if (p.contextId !== contextId)
                 continue;
             clearTimeout(p.timer);
-            p.reject(new DaemonCommandFailure(`Browser profile "${contextId}" disconnected`, 'profile_disconnected', 'Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 503));
+            const failure = buildExtensionDisconnectFailure({
+                contextId,
+                action: p.action,
+                dispatched: p.dispatched,
+            });
+            if (failure.countAsCommandResultUnknown) {
+                commandResultUnknownCount++;
+                log.warn(`[daemon] Command result unknown after extension disconnect (id=${id}, action=${p.action}, context=${contextId})`);
+            }
+            p.reject(new DaemonCommandFailure(failure.message, failure.errorCode, failure.errorHint, failure.status));
             pending.delete(id);
         }
     }
@@ -142,16 +153,6 @@ function jsonResponse(res, status, data, extraHeaders) {
     res.writeHead(status, { 'Content-Type': 'application/json', ...extraHeaders });
     res.end(JSON.stringify(data));
 }
-export function getResponseCorsHeaders(pathname, origin) {
-    if (pathname !== '/ping')
-        return undefined;
-    if (!origin || !origin.startsWith('chrome-extension://'))
-        return undefined;
-    return {
-        'Access-Control-Allow-Origin': origin,
-        Vary: 'Origin',
-    };
-}
 async function handleRequest(req, res) {
     // ─── Security: Origin & custom-header check ──────────────────────
     // Block browser-based CSRF: browsers always send an Origin header on
@@ -219,6 +220,7 @@ async function handleRequest(req, res) {
             profileDisconnected: route.errorCode === 'profile_disconnected',
             profiles,
             pending: pending.size,
+            commandResultUnknown: commandResultUnknownCount,
             memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
             port: PORT,
         });
@@ -277,8 +279,37 @@ async function handleRequest(req, res) {
                     pending.delete(body.id);
                     reject(new Error(`Command timeout (${timeoutMs / 1000}s)`));
                 }, timeoutMs);
-                pending.set(body.id, { contextId: route.connection.contextId, resolve, reject, timer });
-                route.connection.ws.send(JSON.stringify(body));
+                const entry = {
+                    contextId: route.connection.contextId,
+                    action: typeof body.action === 'string' ? body.action : 'unknown',
+                    dispatched: false,
+                    resolve,
+                    reject,
+                    timer,
+                };
+                pending.set(body.id, entry);
+                const failBeforeDispatch = (err) => {
+                    if (pending.get(body.id) !== entry)
+                        return;
+                    const failure = buildCommandDispatchFailure(entry.contextId);
+                    clearTimeout(timer);
+                    pending.delete(body.id);
+                    reject(new DaemonCommandFailure(failure.message, failure.errorCode, failure.errorHint, failure.status));
+                    log.warn(`[daemon] Failed to dispatch command ${body.id}: ${err instanceof Error ? err.message : String(err)}`);
+                };
+                try {
+                    route.connection.ws.send(JSON.stringify(body), (err) => {
+                        if (err && !entry.dispatched)
+                            failBeforeDispatch(err);
+                    });
+                    // Once ws accepts the frame, the command may execute even if the
+                    // result is later lost; do not downgrade later disconnects to a
+                    // pre-dispatch failure just because no result/ack has arrived yet.
+                    entry.dispatched = true;
+                }
+                catch (err) {
+                    failBeforeDispatch(err);
+                }
             });
             jsonResponse(res, 200, result);
         }

package/dist/src/daemon.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { getResponseCorsHeaders } from './daemon.js';
+import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT, buildCommandDispatchFailure, buildExtensionDisconnectFailure, commandResultUnknownMessage, getResponseCorsHeaders, } from './daemon-utils.js';
 describe('getResponseCorsHeaders', () => {
     it('allows the Browser Bridge extension origin to read /ping', () => {
         expect(getResponseCorsHeaders('/ping', 'chrome-extension://abc123')).toEqual({
@@ -17,3 +17,44 @@ describe('getResponseCorsHeaders', () => {
         expect(getResponseCorsHeaders('/command', 'chrome-extension://abc123')).toBeUndefined();
     });
 });
+describe('daemon command dispatch', () => {
+    it('uses a distinct command_result_unknown contract for ambiguous dispatched commands', () => {
+        expect(COMMAND_RESULT_UNKNOWN_CODE).toBe('command_result_unknown');
+        expect(commandResultUnknownMessage('navigate')).toContain('navigate command was dispatched');
+        expect(COMMAND_RESULT_UNKNOWN_HINT).toContain('Inspect the browser/session state');
+        expect(COMMAND_RESULT_UNKNOWN_HINT).toContain('Do not blindly retry write commands');
+    });
+    it('classifies dispatched extension disconnects as command_result_unknown', () => {
+        expect(buildExtensionDisconnectFailure({
+            contextId: 'work',
+            action: 'navigate',
+            dispatched: true,
+        })).toEqual({
+            message: 'Browser connection dropped after the navigate command was dispatched; it may have completed.',
+            errorCode: 'command_result_unknown',
+            errorHint: COMMAND_RESULT_UNKNOWN_HINT,
+            status: 503,
+            countAsCommandResultUnknown: true,
+        });
+    });
+    it('classifies pre-dispatch extension disconnects as profile_disconnected', () => {
+        expect(buildExtensionDisconnectFailure({
+            contextId: 'work',
+            action: 'navigate',
+            dispatched: false,
+        })).toMatchObject({
+            message: 'Browser profile "work" disconnected before command dispatch',
+            errorCode: 'profile_disconnected',
+            status: 503,
+            countAsCommandResultUnknown: false,
+        });
+    });
+    it('classifies ws.send dispatch failures as profile_disconnected', () => {
+        expect(buildCommandDispatchFailure('work')).toMatchObject({
+            message: 'Browser profile "work" disconnected before command dispatch',
+            errorCode: 'profile_disconnected',
+            status: 503,
+            countAsCommandResultUnknown: false,
+        });
+    });
+});

package/dist/src/electron-apps.js

@@ -12,7 +12,6 @@ export const builtinApps = {
     cursor: { port: 9226, processName: 'Cursor', bundleId: 'com.todesktop.runtime.Cursor', displayName: 'Cursor' },
     codex: { port: 9222, processName: 'Codex', bundleId: 'com.openai.codex', displayName: 'Codex' },
     chatwise: { port: 9228, processName: 'ChatWise', bundleId: 'com.chatwise.app', displayName: 'ChatWise' },
-    notion: { port: 9230, processName: 'Notion', bundleId: 'notion.id', displayName: 'Notion' },
     'discord-app': { port: 9232, processName: 'Discord', bundleId: 'com.discord.app', displayName: 'Discord' },
     'doubao-app': { port: 9225, processName: 'Doubao', bundleId: 'com.volcengine.doubao', displayName: 'Doubao' },
     antigravity: {

package/dist/src/electron-apps.test.js

@@ -23,6 +23,7 @@ describe('electron-apps registry', () => {
     });
     it('isElectronApp returns false for non-Electron sites', () => {
         expect(isElectronApp('bilibili')).toBe(false);
+        expect(isElectronApp('notion')).toBe(false);
         expect(isElectronApp('unknown-app')).toBe(false);
     });
     it('loadApps merges user config additively', () => {

package/dist/src/external-clis.yaml

@@ -14,6 +14,12 @@
   install:
     mac: "brew install --cask obsidian"
 
+- name: ntn
+  binary: ntn
+  description: "Notion CLI — official Notion API CLI for pages, databases, blocks, search, comments"
+  homepage: "https://ntn.dev"
+  tags: [notion, notes, knowledge, productivity]
+
 - name: docker
   binary: docker
   description: "Docker command-line interface"
@@ -55,24 +61,27 @@
   install:
     default: "npm install -g vercel"
 
-- name: tg-cli
+- name: tg
   binary: tg
+  package: tg-cli
   description: "Telegram CLI — local-first sync, search, export via MTProto for AI agents"
   homepage: "https://github.com/jackwener/tg-cli"
   tags: [telegram, messaging, search, export, ai-agent]
   install:
     default: "uv tool install kabi-tg-cli"
 
-- name: discord-cli
+- name: discord
   binary: discord
+  package: discord-cli
   description: "Discord CLI — local-first sync, search, export via SQLite for AI agents"
   homepage: "https://github.com/jackwener/discord-cli"
   tags: [discord, messaging, search, export, ai-agent]
   install:
     default: "uv tool install kabi-discord-cli"
 
-- name: wx-cli
+- name: wx
   binary: wx
+  package: wx-cli
   description: "WeChat local data CLI — sessions, messages, search, contacts, export for AI agents"
   homepage: "https://github.com/jackwener/wx-cli"
   tags: [wechat, messaging, search, export, ai-agent]

package/dist/src/external.d.ts

@@ -5,8 +5,11 @@ export interface ExternalCliInstall {
     default?: string;
 }
 export interface ExternalCliConfig {
+    /** User-facing OpenCLI subcommand and, by default, the executable name. */
     name: string;
     binary: string;
+    /** Distribution/project name when it differs from the executable name. */
+    package?: string;
     description?: string;
     homepage?: string;
     tags?: string[];
@@ -15,6 +18,7 @@ export interface ExternalCliConfig {
 export declare function loadExternalClis(): ExternalCliConfig[];
 export declare function isBinaryInstalled(binary: string): boolean;
 export declare function getInstallCmd(installConfig?: ExternalCliInstall): string | null;
+export declare function formatExternalCliLabel(cli: ExternalCliConfig): string;
 /**
  * Safely parses a command string into a binary and argument list.
  * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that

package/dist/src/external.js

@@ -70,6 +70,9 @@ export function getInstallCmd(installConfig) {
         return installConfig.default;
     return null;
 }
+export function formatExternalCliLabel(cli) {
+    return cli.package && cli.package !== cli.name ? `${cli.name}(${cli.package})` : cli.name;
+}
 /**
  * Safely parses a command string into a binary and argument list.
  * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that

package/dist/src/external.test.js

@@ -1,4 +1,8 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
 const { mockExecFileSync, mockPlatform } = vi.hoisted(() => ({
     mockExecFileSync: vi.fn(),
     mockPlatform: vi.fn(() => 'darwin'),
@@ -14,7 +18,8 @@ vi.mock('node:os', async () => {
         platform: mockPlatform,
     };
 });
-import { installExternalCli, parseCommand } from './external.js';
+import { formatExternalCliLabel, installExternalCli, parseCommand } from './external.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 describe('parseCommand', () => {
     it('splits binaries and quoted arguments without invoking a shell', () => {
         expect(parseCommand('npm install -g "@scope/tool name"')).toEqual({
@@ -29,6 +34,24 @@ describe('parseCommand', () => {
         expect(() => parseCommand('brew install $(whoami)')).toThrow('Install command contains unsafe shell operators');
         expect(() => parseCommand('brew install gh\nrm -rf /')).toThrow('Install command contains unsafe shell operators');
     });
+    it('keeps built-in install commands compatible with the shell-free parser', () => {
+        const raw = fs.readFileSync(path.join(__dirname, 'external-clis.yaml'), 'utf8');
+        const entries = (yaml.load(raw) || []);
+        for (const entry of entries) {
+            for (const command of Object.values(entry.install ?? {})) {
+                if (command)
+                    expect(() => parseCommand(command)).not.toThrow();
+            }
+        }
+    });
+});
+describe('formatExternalCliLabel', () => {
+    it('shows the package name when the executable name differs', () => {
+        expect(formatExternalCliLabel({ name: 'wx', binary: 'wx', package: 'wx-cli' })).toBe('wx(wx-cli)');
+    });
+    it('keeps the label compact when package and name match', () => {
+        expect(formatExternalCliLabel({ name: 'docker', binary: 'docker', package: 'docker' })).toBe('docker');
+    });
 });
 describe('installExternalCli', () => {
     const cli = {