@jackwener/opencli 1.5.5 → 1.5.7

package/dist/engine.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { discoverClis, discoverPlugins, PLUGINS_DIR } from './discovery.js';
+import { discoverClis, discoverPlugins, ensureUserCliCompatShims, PLUGINS_DIR } from './discovery.js';
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
 import { clearAllHooks, onAfterExecute } from './hooks.js';
@@ -71,6 +71,36 @@ cli({
             await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
         }
     });
+    it('loads legacy user TS CLI modules via compatibility shims', async () => {
+        const tempOpencliRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-user-clis-'));
+        const userClisDir = path.join(tempOpencliRoot, 'clis');
+        const siteDir = path.join(userClisDir, 'legacy-site');
+        const commandPath = path.join(siteDir, 'hello.ts');
+        try {
+            await ensureUserCliCompatShims(tempOpencliRoot);
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '../../registry';
+import { CommandExecutionError } from '../../errors';
+
+cli({
+  site: 'legacy-site',
+  name: 'hello',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true, errorName: new CommandExecutionError('boom').name }],
+});
+`);
+            await discoverClis(userClisDir);
+            const cmd = getRegistry().get('legacy-site/hello');
+            expect(cmd).toBeDefined();
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true, errorName: 'CommandExecutionError' }]);
+        }
+        finally {
+            await fs.promises.rm(tempOpencliRoot, { recursive: true, force: true });
+        }
+    });
 });
 describe('discoverPlugins', () => {
     const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
@@ -245,21 +275,23 @@ describe('executeCommand', () => {
         expect(seen[0].error.message).toBe('boom');
         expect(typeof seen[0].finishedAt).toBe('number');
     });
-    it('fails fast for chatwise commands when OPENCLI_CDP_ENDPOINT is missing', async () => {
+    it('uses launcher for registered Electron apps (chatwise)', async () => {
+        // Mock the launcher to return a fake endpoint (avoids real HTTP/process calls)
+        const launcher = await import('./launcher.js');
+        const spy = vi.spyOn(launcher, 'resolveElectronEndpoint')
+            .mockResolvedValue('http://127.0.0.1:9228');
         const cmd = cli({
             site: 'chatwise',
             name: 'status',
             description: 'chatwise status',
             browser: true,
             strategy: Strategy.PUBLIC,
-            requiredEnv: [
-                {
-                    name: 'OPENCLI_CDP_ENDPOINT',
-                    help: 'Set OPENCLI_CDP_ENDPOINT before running chatwise commands.',
-                },
-            ],
             func: async () => [{ ok: true }],
         });
-        await expect(executeCommand(cmd, {})).rejects.toThrow('requires environment variable OPENCLI_CDP_ENDPOINT');
+        // CDPBridge.connect() will fail (no actual CDP server), but the launcher
+        // should have been called with 'chatwise'.
+        await expect(executeCommand(cmd, {})).rejects.toThrow();
+        expect(spy).toHaveBeenCalledWith('chatwise');
+        spy.mockRestore();
     });
 });

package/dist/execution.js

@@ -18,6 +18,8 @@ import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMM
 import { emitHook } from './hooks.js';
 import { checkDaemonStatus } from './browser/discover.js';
 import { log } from './logger.js';
+import { isElectronApp } from './electron-apps.js';
+import { resolveElectronEndpoint } from './launcher.js';
 const _loadedModules = new Set();
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
@@ -147,21 +149,25 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
     let result;
     try {
         if (shouldUseBrowserSession(cmd)) {
-            // ── Fail-fast: only when daemon is UP but extension is not connected ──
-            // If daemon is not running, let browserSession() handle auto-start as usual.
-            // We only short-circuit when the daemon confirms the extension is missing —
-            // that's a clear setup gap, not a transient startup state.
-            // Use a short timeout: localhost responds in <50ms when running.
-            // 300ms avoids a full 2s wait on cold-start (daemon not yet running).
-            const status = await checkDaemonStatus({ timeout: 300 });
-            if (status.running && !status.extensionConnected) {
-                throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
-                    '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                    '  2. chrome://extensions → Developer Mode → Load unpacked\n' +
-                    '  Then run: opencli doctor');
+            const electron = isElectronApp(cmd.site);
+            let cdpEndpoint;
+            if (electron) {
+                // Electron apps: auto-detect, prompt restart if needed, launch with CDP
+                cdpEndpoint = await resolveElectronEndpoint(cmd.site);
+            }
+            else {
+                // Browser Bridge: fail-fast when daemon is up but extension is missing.
+                // 300ms timeout avoids a full 2s wait on cold-start.
+                const status = await checkDaemonStatus({ timeout: 300 });
+                if (status.running && !status.extensionConnected) {
+                    throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+                        '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                        '  2. chrome://extensions → Developer Mode → Load unpacked\n' +
+                        '  Then run: opencli doctor');
+                }
             }
             ensureRequiredEnv(cmd);
-            const BrowserFactory = getBrowserFactory();
+            const BrowserFactory = getBrowserFactory(cmd.site);
             result = await browserSession(BrowserFactory, async (page) => {
                 const preNavUrl = resolvePreNav(cmd);
                 if (preNavUrl) {
@@ -172,8 +178,6 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
                     }
                     else {
                         try {
-                            // goto() already includes smart DOM-settle detection (waitForDomStable).
-                            // No additional fixed sleep needed.
                             await page.goto(preNavUrl);
                         }
                         catch (err) {
@@ -186,7 +190,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
                     timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
                     label: fullName(cmd),
                 });
-            }, { workspace: `site:${cmd.site}` });
+            }, { workspace: `site:${cmd.site}`, cdpEndpoint });
         }
         else {
             // Non-browser commands: apply timeout only when explicitly configured.

package/dist/external-clis.yaml

@@ -30,6 +30,23 @@
   install:
     default: "npm install -g @larksuite/cli"
 
+- name: dws
+  binary: dws
+  description: "DingTalk Workspace CLI — messages, docs, calendar, contacts and more for humans and AI agents"
+  homepage: "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  tags: [dingtalk, collaboration, productivity, ai-agent]
+  install:
+    mac: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+    linux: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+
+- name: wecom-cli
+  binary: wecom-cli
+  description: "WeCom/企业微信 CLI — contacts, todos, meetings, messages, calendar, docs and smart sheets for AI agents"
+  homepage: "https://github.com/WecomTeam/wecom-cli"
+  tags: [wecom, wechat-work, collaboration, productivity, ai-agent]
+  install:
+    default: "npm install -g @wecom/cli"
+
 - name: vercel
   binary: vercel
   description: "Vercel CLI — deploy projects, manage domains, env vars, logs and serverless functions"

package/dist/idle-manager.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Manages daemon idle timeout with dual-condition logic:
+ * exits only when BOTH CLI is idle AND Extension is disconnected.
+ */
+export declare class IdleManager {
+    private _timer;
+    private _lastCliRequestTime;
+    private _extensionConnected;
+    private _timeoutMs;
+    private _onExit;
+    constructor(timeoutMs: number, onExit: () => void);
+    get lastCliRequestTime(): number;
+    /** Call when an HTTP request arrives from CLI */
+    onCliRequest(): void;
+    /** Call when Extension WebSocket connects or disconnects */
+    setExtensionConnected(connected: boolean): void;
+    private _clearTimer;
+    private _resetTimer;
+}

package/dist/idle-manager.js

@@ -0,0 +1,54 @@
+/**
+ * Manages daemon idle timeout with dual-condition logic:
+ * exits only when BOTH CLI is idle AND Extension is disconnected.
+ */
+export class IdleManager {
+    _timer = null;
+    _lastCliRequestTime = Date.now();
+    _extensionConnected = false;
+    _timeoutMs;
+    _onExit;
+    constructor(timeoutMs, onExit) {
+        this._timeoutMs = timeoutMs;
+        this._onExit = onExit;
+    }
+    get lastCliRequestTime() {
+        return this._lastCliRequestTime;
+    }
+    /** Call when an HTTP request arrives from CLI */
+    onCliRequest() {
+        this._lastCliRequestTime = Date.now();
+        this._resetTimer();
+    }
+    /** Call when Extension WebSocket connects or disconnects */
+    setExtensionConnected(connected) {
+        this._extensionConnected = connected;
+        if (connected) {
+            this._clearTimer();
+        }
+        else {
+            this._resetTimer();
+        }
+    }
+    _clearTimer() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+    _resetTimer() {
+        this._clearTimer();
+        if (this._timeoutMs <= 0)
+            return;
+        if (this._extensionConnected)
+            return;
+        const elapsed = Date.now() - this._lastCliRequestTime;
+        if (elapsed >= this._timeoutMs) {
+            this._onExit();
+            return;
+        }
+        this._timer = setTimeout(() => {
+            this._onExit();
+        }, this._timeoutMs - elapsed);
+    }
+}

package/dist/launcher.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Electron app launcher — auto-detect, confirm, launch, and connect.
+ *
+ * Flow:
+ * 1. Probe CDP port → already running with debug? connect directly
+ * 2. Detect process → running without CDP? prompt to restart
+ * 3. Discover app path → not installed? error
+ * 4. Launch with --remote-debugging-port
+ * 5. Poll /json until ready
+ */
+/**
+ * Probe whether a CDP endpoint is listening on the given port.
+ * Returns true if http://127.0.0.1:{port}/json responds successfully.
+ */
+export declare function probeCDP(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Check if a process with the given name is running.
+ * Uses pgrep on macOS/Linux.
+ */
+export declare function detectProcess(processName: string): boolean;
+/**
+ * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
+ */
+export declare function killProcess(processName: string): void;
+/**
+ * Discover the app installation path on macOS.
+ * Uses osascript to resolve the app name to a POSIX path.
+ * Returns null if the app is not installed.
+ */
+export declare function discoverAppPath(displayName: string): string | null;
+/**
+ * Main entry point: resolve an Electron app to a CDP endpoint URL.
+ *
+ * Returns the endpoint URL: http://127.0.0.1:{port}
+ */
+export declare function resolveElectronEndpoint(site: string): Promise<string>;

package/dist/launcher.js

@@ -0,0 +1,152 @@
+/**
+ * Electron app launcher — auto-detect, confirm, launch, and connect.
+ *
+ * Flow:
+ * 1. Probe CDP port → already running with debug? connect directly
+ * 2. Detect process → running without CDP? prompt to restart
+ * 3. Discover app path → not installed? error
+ * 4. Launch with --remote-debugging-port
+ * 5. Poll /json until ready
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import { request as httpRequest } from 'node:http';
+import { getElectronApp } from './electron-apps.js';
+import { confirmPrompt } from './tui.js';
+import { CommandExecutionError } from './errors.js';
+import { log } from './logger.js';
+const POLL_INTERVAL_MS = 500;
+const POLL_TIMEOUT_MS = 15_000;
+const PROBE_TIMEOUT_MS = 2_000;
+const KILL_GRACE_MS = 3_000;
+/**
+ * Probe whether a CDP endpoint is listening on the given port.
+ * Returns true if http://127.0.0.1:{port}/json responds successfully.
+ */
+export function probeCDP(port, timeoutMs = PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const req = httpRequest({ hostname: '127.0.0.1', port, path: '/json', method: 'GET', timeout: timeoutMs }, (res) => {
+            res.resume();
+            resolve(res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 300);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.end();
+    });
+}
+/**
+ * Check if a process with the given name is running.
+ * Uses pgrep on macOS/Linux.
+ */
+export function detectProcess(processName) {
+    try {
+        execFileSync('pgrep', ['-x', processName], { encoding: 'utf-8', stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
+ */
+export function killProcess(processName) {
+    try {
+        execFileSync('pkill', ['-x', processName], { stdio: 'pipe' });
+    }
+    catch {
+        // Process may have already exited
+    }
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (Date.now() < deadline) {
+        if (!detectProcess(processName))
+            return;
+        execFileSync('sleep', ['0.2'], { stdio: 'pipe' });
+    }
+    try {
+        execFileSync('pkill', ['-9', '-x', processName], { stdio: 'pipe' });
+    }
+    catch {
+        // Ignore
+    }
+}
+/**
+ * Discover the app installation path on macOS.
+ * Uses osascript to resolve the app name to a POSIX path.
+ * Returns null if the app is not installed.
+ */
+export function discoverAppPath(displayName) {
+    if (process.platform !== 'darwin') {
+        return null;
+    }
+    try {
+        const result = execFileSync('osascript', [
+            '-e', `POSIX path of (path to application "${displayName}")`,
+        ], { encoding: 'utf-8', stdio: 'pipe', timeout: 5_000 });
+        return result.trim().replace(/\/$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+function resolveExecutable(appPath, processName) {
+    return `${appPath}/Contents/MacOS/${processName}`;
+}
+async function pollForReady(port) {
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await probeCDP(port, 1_000))
+            return;
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    throw new CommandExecutionError(`App launched but CDP not available on port ${port} after ${POLL_TIMEOUT_MS / 1000}s`, 'The app may be slow to start. Try running the command again.');
+}
+/**
+ * Main entry point: resolve an Electron app to a CDP endpoint URL.
+ *
+ * Returns the endpoint URL: http://127.0.0.1:{port}
+ */
+export async function resolveElectronEndpoint(site) {
+    const app = getElectronApp(site);
+    if (!app) {
+        throw new CommandExecutionError(`No Electron app registered for site "${site}"`, 'Register the app in ~/.opencli/apps.yaml or check the site name.');
+    }
+    const { port, processName, displayName } = app;
+    const label = displayName ?? processName;
+    const endpoint = `http://127.0.0.1:${port}`;
+    // Step 1: Already running with CDP?
+    log.debug(`[launcher] Probing CDP on port ${port}...`);
+    if (await probeCDP(port)) {
+        log.debug(`[launcher] CDP already available on port ${port}`);
+        return endpoint;
+    }
+    // Step 2: Running without CDP?
+    const isRunning = detectProcess(processName);
+    if (isRunning) {
+        log.debug(`[launcher] ${label} is running but CDP not available`);
+        const confirmed = await confirmPrompt(`${label} is running but CDP is not enabled. Restart with debug port?`, true);
+        if (!confirmed) {
+            throw new CommandExecutionError(`${label} needs to be restarted with CDP enabled.`, `Manually restart: kill the app and relaunch with --remote-debugging-port=${port}`);
+        }
+        process.stderr.write(`  Restarting ${label}...\n`);
+        killProcess(processName);
+    }
+    // Step 3: Discover path
+    const appPath = discoverAppPath(label);
+    if (!appPath) {
+        throw new CommandExecutionError(`Could not find ${label} on this machine.`, `Install ${label} or register a custom path in ~/.opencli/apps.yaml`);
+    }
+    // Step 4: Launch
+    const executable = resolveExecutable(appPath, processName);
+    const args = [`--remote-debugging-port=${port}`, ...(app.extraArgs ?? [])];
+    log.debug(`[launcher] Launching: ${executable} ${args.join(' ')}`);
+    const child = spawn(executable, args, {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    // Step 5: Poll for readiness
+    process.stderr.write(`  Waiting for ${label} on port ${port}...\n`);
+    await pollForReady(port);
+    process.stderr.write(`  Connected to ${label} on port ${port}.\n`);
+    return endpoint;
+}

package/dist/launcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/launcher.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { probeCDP, detectProcess, discoverAppPath } from './launcher.js';
+vi.mock('node:child_process', () => ({
+    execFileSync: vi.fn(),
+    spawn: vi.fn(() => ({
+        unref: vi.fn(),
+        pid: 12345,
+        on: vi.fn(),
+    })),
+}));
+const cp = vi.mocked(await import('node:child_process'));
+describe('probeCDP', () => {
+    it('returns false when CDP endpoint is unreachable', async () => {
+        const result = await probeCDP(59999, 500);
+        expect(result).toBe(false);
+    });
+});
+describe('detectProcess', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns false when pgrep finds no process', () => {
+        cp.execFileSync.mockImplementation(() => {
+            const err = new Error('exit 1');
+            err.status = 1;
+            throw err;
+        });
+        const result = detectProcess('NonExistentApp');
+        expect(result).toBe(false);
+    });
+    it('returns true when pgrep finds a process', () => {
+        cp.execFileSync.mockReturnValue('12345\n');
+        const result = detectProcess('Cursor');
+        expect(result).toBe(true);
+    });
+});
+describe('discoverAppPath', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it.skipIf(process.platform !== 'darwin')('returns path when osascript succeeds', () => {
+        cp.execFileSync.mockReturnValue('/Applications/Cursor.app/\n');
+        const result = discoverAppPath('Cursor');
+        expect(result).toBe('/Applications/Cursor.app');
+    });
+    it.skipIf(process.platform !== 'darwin')('returns null when osascript fails', () => {
+        cp.execFileSync.mockImplementation(() => {
+            throw new Error('app not found');
+        });
+        const result = discoverAppPath('NonExistent');
+        expect(result).toBeNull();
+    });
+    it.skipIf(process.platform === 'darwin')('returns null on non-darwin platform', () => {
+        const result = discoverAppPath('Cursor');
+        expect(result).toBeNull();
+    });
+});

package/dist/main.js

@@ -12,10 +12,9 @@ if (process.platform !== 'win32') {
         cur.add(p);
     process.env.PATH = [...cur].join(':');
 }
-import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverClis, discoverPlugins } from './discovery.js';
+import { discoverClis, discoverPlugins, ensureUserCliCompatShims, USER_CLIS_DIR } from './discovery.js';
 import { getCompletions } from './completion.js';
 import { runCli } from './cli.js';
 import { emitHook } from './hooks.js';
@@ -26,8 +25,9 @@ installNodeNetwork();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
-const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
+const USER_CLIS = USER_CLIS_DIR;
 // Sequential: plugins must run after built-in discovery so they can override built-in commands.
+await ensureUserCliCompatShims();
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
 await discoverPlugins();
 // Register exit hook: notice appears after command output (same as npm/gh/yarn)

package/dist/registry.d.ts

@@ -26,6 +26,7 @@ export type CommandArgs = Record<string, any>;
 export interface CliCommand {
     site: string;
     name: string;
+    aliases?: string[];
     description: string;
     domain?: string;
     strategy?: Strategy;

package/dist/registry.js

@@ -13,9 +13,11 @@ const _registry = globalThis.__opencli_registry__ ??= new Map();
 export function cli(opts) {
     const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     const browser = opts.browser ?? (strategy !== Strategy.PUBLIC);
+    const aliases = normalizeAliases(opts.aliases, opts.name);
     const cmd = {
         site: opts.site,
         name: opts.name,
+        aliases,
         description: opts.description ?? '',
         domain: opts.domain,
         strategy,
@@ -31,8 +33,7 @@ export function cli(opts) {
         replacedBy: opts.replacedBy,
         navigateBefore: opts.navigateBefore,
     };
-    const key = fullName(cmd);
-    _registry.set(key, cmd);
+    registerCommand(cmd);
     return cmd;
 }
 export function getRegistry() {
@@ -45,5 +46,32 @@ export function strategyLabel(cmd) {
     return cmd.strategy ?? Strategy.PUBLIC;
 }
 export function registerCommand(cmd) {
-    _registry.set(fullName(cmd), cmd);
+    const canonicalKey = fullName(cmd);
+    const existing = _registry.get(canonicalKey);
+    if (existing) {
+        for (const [key, value] of _registry.entries()) {
+            if (value === existing && key !== canonicalKey)
+                _registry.delete(key);
+        }
+    }
+    const aliases = normalizeAliases(cmd.aliases, cmd.name);
+    cmd.aliases = aliases.length > 0 ? aliases : undefined;
+    _registry.set(canonicalKey, cmd);
+    for (const alias of aliases) {
+        _registry.set(`${cmd.site}/${alias}`, cmd);
+    }
+}
+function normalizeAliases(aliases, commandName) {
+    if (!Array.isArray(aliases) || aliases.length === 0)
+        return [];
+    const seen = new Set();
+    const normalized = [];
+    for (const alias of aliases) {
+        const value = typeof alias === 'string' ? alias.trim() : '';
+        if (!value || value === commandName || seen.has(value))
+            continue;
+        seen.add(value);
+        normalized.push(value);
+    }
+    return normalized;
 }

package/dist/registry.test.js

@@ -49,6 +49,19 @@ describe('cli() registration', () => {
         const reg = getRegistry();
         expect(reg.get('test-registry/overwrite')?.description).toBe('v2');
     });
+    it('registers aliases as alternate registry keys for the same command', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'canonical',
+            description: 'test aliases',
+            aliases: ['compat', 'legacy-name'],
+        });
+        const registry = getRegistry();
+        expect(cmd.aliases).toEqual(['compat', 'legacy-name']);
+        expect(registry.get('test-registry/canonical')).toBe(cmd);
+        expect(registry.get('test-registry/compat')).toBe(cmd);
+        expect(registry.get('test-registry/legacy-name')).toBe(cmd);
+    });
 });
 describe('fullName', () => {
     it('returns site/name', () => {

package/dist/runtime.d.ts

@@ -1,9 +1,9 @@
 import type { IPage } from './types.js';
 /**
- * Returns the appropriate browser factory based on environment config.
- * Uses CDPBridge when OPENCLI_CDP_ENDPOINT is set, otherwise BrowserBridge.
+ * Returns the appropriate browser factory based on site type.
+ * Uses CDPBridge for registered Electron apps, otherwise BrowserBridge.
  */
-export declare function getBrowserFactory(): new () => IBrowserFactory;
+export declare function getBrowserFactory(site?: string): new () => IBrowserFactory;
 export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_EXPLORE_TIMEOUT: number;
@@ -26,9 +26,11 @@ export interface IBrowserFactory {
     connect(opts?: {
         timeout?: number;
         workspace?: string;
+        cdpEndpoint?: string;
     }): Promise<IPage>;
     close(): Promise<void>;
 }
 export declare function browserSession<T>(BrowserFactory: new () => IBrowserFactory, fn: (page: IPage) => Promise<T>, opts?: {
     workspace?: string;
+    cdpEndpoint?: string;
 }): Promise<T>;

package/dist/runtime.js

@@ -1,11 +1,14 @@
 import { BrowserBridge, CDPBridge } from './browser/index.js';
 import { TimeoutError } from './errors.js';
+import { isElectronApp } from './electron-apps.js';
 /**
- * Returns the appropriate browser factory based on environment config.
- * Uses CDPBridge when OPENCLI_CDP_ENDPOINT is set, otherwise BrowserBridge.
+ * Returns the appropriate browser factory based on site type.
+ * Uses CDPBridge for registered Electron apps, otherwise BrowserBridge.
  */
-export function getBrowserFactory() {
-    return process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge;
+export function getBrowserFactory(site) {
+    if (site && isElectronApp(site))
+        return CDPBridge;
+    return BrowserBridge;
 }
 function parseEnvTimeout(envVar, fallback) {
     const raw = process.env[envVar];
@@ -45,7 +48,11 @@ export function withTimeoutMs(promise, timeoutMs, makeError = 'Operation timed o
 export async function browserSession(BrowserFactory, fn, opts = {}) {
     const mcp = new BrowserFactory();
     try {
-        const page = await mcp.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, workspace: opts.workspace });
+        const page = await mcp.connect({
+            timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,
+            workspace: opts.workspace,
+            cdpEndpoint: opts.cdpEndpoint,
+        });
         return await fn(page);
     }
     finally {

package/dist/serialization.d.ts

@@ -21,6 +21,7 @@ export declare function serializeCommand(cmd: CliCommand): {
     command: string;
     site: string;
     name: string;
+    aliases: string[];
     description: string;
     strategy: string;
     browser: boolean;