@jackwener/opencli 1.5.6 → 1.5.7

package/dist/commands/daemon.js

@@ -0,0 +1,124 @@
+/**
+ * CLI commands for daemon lifecycle management:
+ *   opencli daemon status  — show daemon state
+ *   opencli daemon stop    — graceful shutdown
+ *   opencli daemon restart — stop + respawn
+ */
+import chalk from 'chalk';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
+async function fetchStatus() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2000);
+    try {
+        const res = await fetch(`${DAEMON_URL}/status`, {
+            headers: { 'X-OpenCLI': '1' },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function requestShutdown() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+        const res = await fetch(`${DAEMON_URL}/shutdown`, {
+            method: 'POST',
+            headers: { 'X-OpenCLI': '1' },
+            signal: controller.signal,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function formatUptime(seconds) {
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    if (h > 0)
+        return `${h}h ${m}m`;
+    if (m > 0)
+        return `${m}m`;
+    return `${Math.floor(seconds)}s`;
+}
+function formatTimeSince(timestampMs) {
+    const seconds = (Date.now() - timestampMs) / 1000;
+    if (seconds < 60)
+        return `${Math.floor(seconds)}s ago`;
+    const m = Math.floor(seconds / 60);
+    if (m < 60)
+        return `${m} min ago`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m ago`;
+}
+export async function daemonStatus() {
+    const status = await fetchStatus();
+    if (!status) {
+        console.log(`Daemon: ${chalk.dim('not running')}`);
+        return;
+    }
+    console.log(`Daemon: ${chalk.green('running')} (PID ${status.pid})`);
+    console.log(`Uptime: ${formatUptime(status.uptime)}`);
+    console.log(`Extension: ${status.extensionConnected ? chalk.green('connected') : chalk.yellow('disconnected')}`);
+    console.log(`Last CLI request: ${formatTimeSince(status.lastCliRequestTime)}`);
+    console.log(`Memory: ${status.memoryMB} MB`);
+    console.log(`Port: ${status.port}`);
+}
+export async function daemonStop() {
+    const status = await fetchStatus();
+    if (!status) {
+        console.log(chalk.dim('Daemon is not running.'));
+        return;
+    }
+    const ok = await requestShutdown();
+    if (ok) {
+        console.log(chalk.green('Daemon stopped.'));
+    }
+    else {
+        console.error(chalk.red('Failed to stop daemon.'));
+        process.exitCode = 1;
+    }
+}
+export async function daemonRestart() {
+    const status = await fetchStatus();
+    if (status) {
+        const ok = await requestShutdown();
+        if (!ok) {
+            console.error(chalk.red('Failed to stop daemon.'));
+            process.exitCode = 1;
+            return;
+        }
+        // Wait for daemon to actually exit (poll until unreachable)
+        const deadline = Date.now() + 5000;
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 200));
+            if (!(await fetchStatus()))
+                break;
+        }
+    }
+    // Import BrowserBridge to spawn a new daemon
+    const { BrowserBridge } = await import('../browser/mcp.js');
+    const bridge = new BrowserBridge();
+    try {
+        console.log('Starting daemon...');
+        await bridge.connect({ timeout: 10 });
+        console.log(chalk.green('Daemon restarted.'));
+    }
+    catch (err) {
+        console.error(chalk.red(`Failed to restart daemon: ${err instanceof Error ? err.message : err}`));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/daemon.test.d.ts

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

package/dist/commands/daemon.test.js

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+vi.mock('chalk', () => ({
+    default: {
+        green: (s) => s,
+        yellow: (s) => s,
+        red: (s) => s,
+        dim: (s) => s,
+    },
+}));
+const mockConnect = vi.fn();
+vi.mock('../browser/mcp.js', () => ({
+    BrowserBridge: class {
+        connect = mockConnect;
+    },
+}));
+import { daemonStatus, daemonStop, daemonRestart } from './daemon.js';
+describe('daemon commands', () => {
+    let logSpy;
+    let errorSpy;
+    beforeEach(() => {
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        mockConnect.mockReset();
+    });
+    describe('daemonStatus', () => {
+        it('shows "not running" when daemon is unreachable', async () => {
+            vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+            await daemonStatus();
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
+        });
+        it('shows "not running" when daemon returns non-ok response', async () => {
+            vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false }));
+            await daemonStatus();
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
+        });
+        it('shows daemon info when running', async () => {
+            const status = {
+                ok: true,
+                pid: 12345,
+                uptime: 3661,
+                extensionConnected: true,
+                pending: 0,
+                lastCliRequestTime: Date.now() - 30_000,
+                memoryMB: 64,
+                port: 19825,
+            };
+            vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(status),
+            }));
+            await daemonStatus();
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('running'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('PID 12345'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('1h 1m'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('connected'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('64 MB'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('19825'));
+        });
+        it('shows disconnected when extension is not connected', async () => {
+            const status = {
+                ok: true,
+                pid: 99,
+                uptime: 120,
+                extensionConnected: false,
+                pending: 0,
+                lastCliRequestTime: Date.now() - 5000,
+                memoryMB: 32,
+                port: 19825,
+            };
+            vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(status),
+            }));
+            await daemonStatus();
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('disconnected'));
+        });
+    });
+    describe('daemonStop', () => {
+        it('reports "not running" when daemon is unreachable', async () => {
+            vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+            await daemonStop();
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
+        });
+        it('sends shutdown and reports success', async () => {
+            const statusResponse = {
+                ok: true,
+                json: () => Promise.resolve({
+                    ok: true,
+                    pid: 12345,
+                    uptime: 100,
+                    extensionConnected: true,
+                    pending: 0,
+                    lastCliRequestTime: Date.now(),
+                    memoryMB: 50,
+                    port: 19825,
+                }),
+            };
+            const shutdownResponse = { ok: true };
+            const mockFetch = vi.fn()
+                .mockResolvedValueOnce(statusResponse)
+                .mockResolvedValueOnce(shutdownResponse);
+            vi.stubGlobal('fetch', mockFetch);
+            await daemonStop();
+            // Verify shutdown was called with POST
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            const shutdownCall = mockFetch.mock.calls[1];
+            expect(shutdownCall[0]).toContain('/shutdown');
+            expect(shutdownCall[1]).toMatchObject({ method: 'POST' });
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon stopped'));
+        });
+        it('reports failure when shutdown request fails', async () => {
+            const statusResponse = {
+                ok: true,
+                json: () => Promise.resolve({
+                    ok: true,
+                    pid: 12345,
+                    uptime: 100,
+                    extensionConnected: true,
+                    pending: 0,
+                    lastCliRequestTime: Date.now(),
+                    memoryMB: 50,
+                    port: 19825,
+                }),
+            };
+            const shutdownResponse = { ok: false };
+            const mockFetch = vi.fn()
+                .mockResolvedValueOnce(statusResponse)
+                .mockResolvedValueOnce(shutdownResponse);
+            vi.stubGlobal('fetch', mockFetch);
+            await daemonStop();
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
+        });
+    });
+    describe('daemonRestart', () => {
+        const statusData = {
+            ok: true,
+            pid: 12345,
+            uptime: 100,
+            extensionConnected: true,
+            pending: 0,
+            lastCliRequestTime: Date.now(),
+            memoryMB: 50,
+            port: 19825,
+        };
+        it('starts daemon directly when not running', async () => {
+            vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+            mockConnect.mockResolvedValue(undefined);
+            await daemonRestart();
+            expect(mockConnect).toHaveBeenCalledWith({ timeout: 10 });
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon restarted'));
+        });
+        it('stops then starts when daemon is running', async () => {
+            const mockFetch = vi.fn()
+                // First call: fetchStatus in daemonRestart — daemon is running
+                .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(statusData) })
+                // Second call: requestShutdown — success
+                .mockResolvedValueOnce({ ok: true })
+                // Subsequent calls: polling fetchStatus until unreachable
+                .mockRejectedValue(new Error('ECONNREFUSED'));
+            vi.stubGlobal('fetch', mockFetch);
+            mockConnect.mockResolvedValue(undefined);
+            await daemonRestart();
+            // Verify shutdown was called
+            const shutdownCall = mockFetch.mock.calls[1];
+            expect(shutdownCall[0]).toContain('/shutdown');
+            expect(shutdownCall[1]).toMatchObject({ method: 'POST' });
+            expect(mockConnect).toHaveBeenCalledWith({ timeout: 10 });
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon restarted'));
+        });
+        it('aborts when shutdown fails', async () => {
+            const mockFetch = vi.fn()
+                // fetchStatus — daemon is running
+                .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(statusData) })
+                // requestShutdown — failure
+                .mockResolvedValueOnce({ ok: false });
+            vi.stubGlobal('fetch', mockFetch);
+            await daemonRestart();
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
+            expect(mockConnect).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/completion.js

@@ -50,9 +50,11 @@ export function getCompletions(words, cursor) {
         for (const [, cmd] of getRegistry()) {
             if (cmd.site === site) {
                 subcommands.push(cmd.name);
+                if (cmd.aliases?.length)
+                    subcommands.push(...cmd.aliases);
             }
         }
-        return subcommands.sort();
+        return [...new Set(subcommands)].sort();
     }
     // cursor >= 3 → no further completion
     return [];

package/dist/constants.d.ts

@@ -3,6 +3,8 @@
  */
 /** Default daemon port for HTTP/WebSocket communication with browser extension */
 export declare const DEFAULT_DAEMON_PORT = 19825;
+/** Default idle timeout before daemon auto-exits (ms). Override via OPENCLI_DAEMON_TIMEOUT env var. */
+export declare const DEFAULT_DAEMON_IDLE_TIMEOUT: number;
 /** URL query params that are volatile/ephemeral and should be stripped from patterns */
 export declare const VOLATILE_PARAMS: Set<string>;
 /** Search-related query parameter names */

package/dist/constants.js

@@ -3,6 +3,8 @@
  */
 /** Default daemon port for HTTP/WebSocket communication with browser extension */
 export const DEFAULT_DAEMON_PORT = 19825;
+/** Default idle timeout before daemon auto-exits (ms). Override via OPENCLI_DAEMON_TIMEOUT env var. */
+export const DEFAULT_DAEMON_IDLE_TIMEOUT = 4 * 60 * 60 * 1000; // 4 hours
 /** URL query params that are volatile/ephemeral and should be stripped from patterns */
 export const VOLATILE_PARAMS = new Set([
     'w_rid', 'wts', '_', 'callback', 'timestamp', 't', 'nonce', 'sign',

package/dist/daemon.d.ts

@@ -15,7 +15,7 @@
  *
  * Lifecycle:
  *   - Auto-spawned by opencli on first browser command
- *   - Auto-exits after 5 minutes of idle
+ *   - Auto-exits after idle timeout (default 4h, configurable via OPENCLI_DAEMON_TIMEOUT)
  *   - Listens on localhost:19825
  */
 export {};

package/dist/daemon.js

@@ -15,20 +15,20 @@
  *
  * Lifecycle:
  *   - Auto-spawned by opencli on first browser command
- *   - Auto-exits after 5 minutes of idle
+ *   - Auto-exits after idle timeout (default 4h, configurable via OPENCLI_DAEMON_TIMEOUT)
  *   - Listens on localhost:19825
  */
 import { createServer } from 'node:http';
 import { WebSocketServer, WebSocket } from 'ws';
-import { DEFAULT_DAEMON_PORT } from './constants.js';
+import { DEFAULT_DAEMON_PORT, DEFAULT_DAEMON_IDLE_TIMEOUT } from './constants.js';
 import { EXIT_CODES } from './errors.js';
+import { IdleManager } from './idle-manager.js';
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const IDLE_TIMEOUT = Number(process.env.OPENCLI_DAEMON_TIMEOUT ?? DEFAULT_DAEMON_IDLE_TIMEOUT);
 // ─── State ───────────────────────────────────────────────────────────
 let extensionWs = null;
 let extensionVersion = null;
 const pending = new Map();
-let idleTimer = null;
 const LOG_BUFFER_SIZE = 200;
 const logBuffer = [];
 function pushLog(entry) {
@@ -37,14 +37,10 @@ function pushLog(entry) {
         logBuffer.shift();
 }
 // ─── Idle auto-exit ──────────────────────────────────────────────────
-function resetIdleTimer() {
-    if (idleTimer)
-        clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => {
-        console.error('[daemon] Idle timeout, shutting down');
-        process.exit(EXIT_CODES.SUCCESS);
-    }, IDLE_TIMEOUT);
-}
+const idleManager = new IdleManager(IDLE_TIMEOUT, () => {
+    console.error('[daemon] Idle timeout (no CLI requests + no Extension), shutting down');
+    process.exit(EXIT_CODES.SUCCESS);
+});
 // ─── HTTP Server ─────────────────────────────────────────────────────
 const MAX_BODY = 1024 * 1024; // 1 MB — commands are tiny; this prevents OOM
 function readBody(req) {
@@ -113,11 +109,18 @@ async function handleRequest(req, res) {
         return;
     }
     if (req.method === 'GET' && pathname === '/status') {
+        const uptime = process.uptime();
+        const mem = process.memoryUsage();
         jsonResponse(res, 200, {
             ok: true,
+            pid: process.pid,
+            uptime,
             extensionConnected: extensionWs?.readyState === WebSocket.OPEN,
             extensionVersion,
             pending: pending.size,
+            lastCliRequestTime: idleManager.lastCliRequestTime,
+            memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
+            port: PORT,
         });
         return;
     }
@@ -135,8 +138,13 @@ async function handleRequest(req, res) {
         jsonResponse(res, 200, { ok: true });
         return;
     }
+    if (req.method === 'POST' && pathname === '/shutdown') {
+        jsonResponse(res, 200, { ok: true, message: 'Shutting down' });
+        setTimeout(() => shutdown(), 100);
+        return;
+    }
     if (req.method === 'POST' && url === '/command') {
-        resetIdleTimer();
+        idleManager.onCliRequest();
         try {
             const body = JSON.parse(await readBody(req));
             if (!body.id) {
@@ -188,6 +196,7 @@ wss.on('connection', (ws) => {
     console.error('[daemon] Extension connected');
     extensionWs = ws;
     extensionVersion = null; // cleared until hello message arrives
+    idleManager.setExtensionConnected(true);
     // ── Heartbeat: ping every 15s, close if 2 pongs missed ──
     let missedPongs = 0;
     const heartbeatInterval = setInterval(() => {
@@ -240,6 +249,7 @@ wss.on('connection', (ws) => {
         if (extensionWs === ws) {
             extensionWs = null;
             extensionVersion = null;
+            idleManager.setExtensionConnected(false);
             // Reject all pending requests since the extension is gone
             for (const [id, p] of pending) {
                 clearTimeout(p.timer);
@@ -253,6 +263,7 @@ wss.on('connection', (ws) => {
         if (extensionWs === ws) {
             extensionWs = null;
             extensionVersion = null;
+            idleManager.setExtensionConnected(false);
             // Reject pending requests in case 'close' does not follow this 'error'
             for (const [, p] of pending) {
                 clearTimeout(p.timer);
@@ -265,7 +276,7 @@ wss.on('connection', (ws) => {
 // ─── Start ───────────────────────────────────────────────────────────
 httpServer.listen(PORT, '127.0.0.1', () => {
     console.error(`[daemon] Listening on http://127.0.0.1:${PORT}`);
-    resetIdleTimer();
+    idleManager.onCliRequest();
 });
 httpServer.on('error', (err) => {
     if (err.code === 'EADDRINUSE') {

package/dist/daemon.test.d.ts

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

package/dist/daemon.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { IdleManager } from './idle-manager.js';
+describe('IdleManager', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('does not start timer when extension is connected', () => {
+        const exit = vi.fn();
+        const mgr = new IdleManager(300_000, exit);
+        mgr.setExtensionConnected(true);
+        mgr.onCliRequest();
+        vi.advanceTimersByTime(300_000 + 1000);
+        expect(exit).not.toHaveBeenCalled();
+    });
+    it('starts timer when extension disconnects and CLI is idle', () => {
+        const exit = vi.fn();
+        const mgr = new IdleManager(300_000, exit);
+        mgr.onCliRequest();
+        mgr.setExtensionConnected(true);
+        mgr.setExtensionConnected(false);
+        expect(exit).not.toHaveBeenCalled();
+        vi.advanceTimersByTime(300_000 + 1000);
+        expect(exit).toHaveBeenCalledTimes(1);
+    });
+    it('exits immediately on extension disconnect if CLI has been idle past timeout', () => {
+        const exit = vi.fn();
+        const mgr = new IdleManager(300_000, exit);
+        mgr.onCliRequest();
+        mgr.setExtensionConnected(true); // connect before timeout elapses
+        vi.advanceTimersByTime(400_000); // CLI idle time exceeds timeout, but extension is connected so no exit
+        expect(exit).not.toHaveBeenCalled();
+        mgr.setExtensionConnected(false); // disconnect → should exit immediately since CLI idle > timeout
+        expect(exit).toHaveBeenCalledTimes(1);
+    });
+    it('resets timer on new CLI request', () => {
+        const exit = vi.fn();
+        const mgr = new IdleManager(300_000, exit);
+        mgr.onCliRequest();
+        vi.advanceTimersByTime(200_000);
+        mgr.onCliRequest();
+        vi.advanceTimersByTime(200_000);
+        expect(exit).not.toHaveBeenCalled();
+        vi.advanceTimersByTime(100_001);
+        expect(exit).toHaveBeenCalledTimes(1);
+    });
+    it('does not exit when timeout is 0 (disabled)', () => {
+        const exit = vi.fn();
+        const mgr = new IdleManager(0, exit);
+        mgr.onCliRequest();
+        vi.advanceTimersByTime(24 * 60 * 60 * 1000);
+        expect(exit).not.toHaveBeenCalled();
+    });
+    it('clears timer when extension connects', () => {
+        const exit = vi.fn();
+        const mgr = new IdleManager(300_000, exit);
+        mgr.onCliRequest();
+        vi.advanceTimersByTime(200_000);
+        mgr.setExtensionConnected(true);
+        vi.advanceTimersByTime(200_000);
+        expect(exit).not.toHaveBeenCalled();
+    });
+});

package/dist/discovery.d.ts

@@ -7,8 +7,17 @@
  *    TS modules are loaded lazily only when their command is executed.
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
+/** User runtime directory: ~/.opencli */
+export declare const USER_OPENCLI_DIR: string;
+/** User CLIs directory: ~/.opencli/clis */
+export declare const USER_CLIS_DIR: string;
 /** Plugins directory: ~/.opencli/plugins/ */
 export declare const PLUGINS_DIR: string;
+/**
+ * Create runtime shim files under ~/.opencli so legacy user TS CLIs can keep
+ * importing ../../registry(.js) and ../../errors(.js).
+ */
+export declare function ensureUserCliCompatShims(baseDir?: string): Promise<void>;
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.

package/dist/discovery.js

@@ -10,13 +10,17 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
 import { Strategy, registerCommand } from './registry.js';
 import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
+/** User runtime directory: ~/.opencli */
+export const USER_OPENCLI_DIR = path.join(os.homedir(), '.opencli');
+/** User CLIs directory: ~/.opencli/clis */
+export const USER_CLIS_DIR = path.join(USER_OPENCLI_DIR, 'clis');
 /** Plugins directory: ~/.opencli/plugins/ */
-export const PLUGINS_DIR = path.join(os.homedir(), '.opencli', 'plugins');
+export const PLUGINS_DIR = path.join(USER_OPENCLI_DIR, 'plugins');
 /** Matches files that register commands via cli() or lifecycle hooks */
 const PLUGIN_MODULE_PATTERN = /\b(?:cli|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
 import { parseYamlArgs } from './yaml-schema.js';
@@ -27,6 +31,42 @@ function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
     return Strategy[key] ?? fallback;
 }
 import { isRecord } from './utils.js';
+function resolveHostRuntimeModulePath(moduleName) {
+    const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
+    for (const ext of ['.js', '.ts']) {
+        const candidate = path.join(runtimeDir, `${moduleName}${ext}`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return path.join(runtimeDir, `${moduleName}.js`);
+}
+async function writeCompatShimIfNeeded(filePath, content) {
+    try {
+        const existing = await fs.promises.readFile(filePath, 'utf-8');
+        if (existing === content)
+            return;
+    }
+    catch {
+        // Fall through to write missing shim
+    }
+    await fs.promises.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Create runtime shim files under ~/.opencli so legacy user TS CLIs can keep
+ * importing ../../registry(.js) and ../../errors(.js).
+ */
+export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
+    await fs.promises.mkdir(baseDir, { recursive: true });
+    const registryUrl = pathToFileURL(resolveHostRuntimeModulePath('registry-api')).href;
+    const errorsUrl = pathToFileURL(resolveHostRuntimeModulePath('errors')).href;
+    await Promise.all([
+        writeCompatShimIfNeeded(path.join(baseDir, 'registry'), `export * from '${registryUrl}';\n`),
+        writeCompatShimIfNeeded(path.join(baseDir, 'registry.js'), `export * from '${registryUrl}';\n`),
+        writeCompatShimIfNeeded(path.join(baseDir, 'errors'), `export * from '${errorsUrl}';\n`),
+        writeCompatShimIfNeeded(path.join(baseDir, 'errors.js'), `export * from '${errorsUrl}';\n`),
+        writeCompatShimIfNeeded(path.join(baseDir, 'package.json'), `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`),
+    ]);
+}
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
@@ -63,6 +103,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 const cmd = {
                     site: entry.site,
                     name: entry.name,
+                    aliases: entry.aliases,
                     description: entry.description ?? '',
                     domain: entry.domain,
                     strategy,
@@ -86,6 +127,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 const cmd = {
                     site: entry.site,
                     name: entry.name,
+                    aliases: entry.aliases,
                     description: entry.description ?? '',
                     domain: entry.domain,
                     strategy,
@@ -160,6 +202,9 @@ async function registerYamlCli(filePath, defaultSite) {
         const cmd = {
             site,
             name,
+            aliases: isRecord(cliDef) && Array.isArray(cliDef.aliases)
+                ? cliDef.aliases.filter((value) => typeof value === 'string')
+                : undefined,
             description: cliDef.description ?? '',
             domain: cliDef.domain,
             strategy,

package/dist/electron-apps.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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).
+ */
+export interface ElectronAppEntry {
+    /** CDP debug port (unique per app) */
+    port: number;
+    /** macOS process name for detection via pgrep */
+    processName: string;
+    /** macOS bundle ID for path discovery */
+    bundleId?: string;
+    /** Human-readable name for prompts */
+    displayName?: string;
+    /** Additional launch args beyond --remote-debugging-port */
+    extraArgs?: string[];
+}
+export declare const builtinApps: Record<string, ElectronAppEntry>;
+/** Merge builtin + user-defined apps. User entries are additive only. */
+export declare function loadApps(userApps?: Record<string, Omit<ElectronAppEntry, 'displayName'> & {
+    displayName?: string;
+}>): Record<string, ElectronAppEntry>;
+export declare function getElectronApp(site: string): ElectronAppEntry | undefined;
+export declare function isElectronApp(site: string): boolean;
+/** Get all registered apps (builtin + user-defined). */
+export declare function getAllElectronApps(): Record<string, ElectronAppEntry>;
+/** Reset loaded apps (for testing). */
+export declare function _resetRegistry(): void;