@jackwener/opencli 1.5.6 → 1.5.7

package/dist/electron-apps.js

@@ -0,0 +1,65 @@
+/**
+ * Electron app registry — maps site names to launch metadata.
+ *
+ * Builtin apps are defined here. User-defined apps are loaded
+ * from ~/.opencli/apps.yaml (additive only, does not override builtins).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import yaml from 'js-yaml';
+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: { port: 9234, processName: 'Antigravity', bundleId: 'dev.antigravity.app', displayName: 'Antigravity' },
+    chatgpt: { port: 9236, processName: 'ChatGPT', bundleId: 'com.openai.chat', displayName: 'ChatGPT' },
+};
+/** Merge builtin + user-defined apps. User entries are additive only. */
+export function loadApps(userApps) {
+    const merged = { ...builtinApps };
+    if (userApps) {
+        for (const [name, entry] of Object.entries(userApps)) {
+            if (!(name in merged)) {
+                merged[name] = entry;
+            }
+        }
+    }
+    return merged;
+}
+let _apps = null;
+function ensureLoaded() {
+    if (_apps)
+        return _apps;
+    let userApps;
+    try {
+        const yamlPath = path.join(os.homedir(), '.opencli', 'apps.yaml');
+        if (fs.existsSync(yamlPath)) {
+            const content = fs.readFileSync(yamlPath, 'utf-8');
+            const parsed = yaml.load(content);
+            userApps = parsed?.apps;
+        }
+    }
+    catch {
+        // Silently ignore malformed user config
+    }
+    _apps = loadApps(userApps);
+    return _apps;
+}
+export function getElectronApp(site) {
+    return ensureLoaded()[site];
+}
+export function isElectronApp(site) {
+    return site in ensureLoaded();
+}
+/** Get all registered apps (builtin + user-defined). */
+export function getAllElectronApps() {
+    return ensureLoaded();
+}
+/** Reset loaded apps (for testing). */
+export function _resetRegistry() {
+    _apps = null;
+}

package/dist/electron-apps.test.d.ts

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

package/dist/electron-apps.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { getElectronApp, isElectronApp, loadApps } from './electron-apps.js';
+describe('electron-apps registry', () => {
+    it('returns builtin app entry for cursor', () => {
+        const app = getElectronApp('cursor');
+        expect(app).toBeDefined();
+        expect(app.port).toBe(9226);
+        expect(app.processName).toBe('Cursor');
+    });
+    it('returns builtin app entry for codex', () => {
+        const app = getElectronApp('codex');
+        expect(app).toBeDefined();
+        expect(app.port).toBe(9222);
+    });
+    it('returns undefined for non-Electron sites', () => {
+        expect(getElectronApp('bilibili')).toBeUndefined();
+        expect(getElectronApp('hackernews')).toBeUndefined();
+    });
+    it('isElectronApp returns true for registered apps', () => {
+        expect(isElectronApp('cursor')).toBe(true);
+        expect(isElectronApp('codex')).toBe(true);
+        expect(isElectronApp('chatwise')).toBe(true);
+    });
+    it('isElectronApp returns false for non-Electron sites', () => {
+        expect(isElectronApp('bilibili')).toBe(false);
+        expect(isElectronApp('unknown-app')).toBe(false);
+    });
+    it('loadApps merges user config additively', () => {
+        const apps = loadApps({
+            myapp: { port: 9234, processName: 'MyApp' },
+        });
+        expect(apps.myapp).toBeDefined();
+        expect(apps.myapp.port).toBe(9234);
+        // Builtins still present
+        expect(apps.cursor).toBeDefined();
+    });
+    it('loadApps does not override builtin entries', () => {
+        const apps = loadApps({
+            cursor: { port: 9999, processName: 'FakeCursor' },
+        });
+        expect(apps.cursor.port).toBe(9226); // Builtin wins
+    });
+});

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/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;
 }