@jackwener/opencli 1.5.5 → 1.5.7

package/src/commands/daemon.ts

@@ -0,0 +1,135 @@
+/**
+ * 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}`;
+
+interface DaemonStatus {
+  ok: boolean;
+  pid: number;
+  uptime: number;
+  extensionConnected: boolean;
+  pending: number;
+  lastCliRequestTime: number;
+  memoryMB: number;
+  port: number;
+}
+
+async function fetchStatus(): Promise<DaemonStatus | null> {
+  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() as DaemonStatus;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function requestShutdown(): Promise<boolean> {
+  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: number): string {
+  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: number): string {
+  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(): Promise<void> {
+  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(): Promise<void> {
+  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(): Promise<void> {
+  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/src/completion.ts

@@ -57,9 +57,10 @@ export function getCompletions(words: string[], cursor: number): string[] {
     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

package/src/constants.ts

@@ -5,6 +5,9 @@
 /** 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/src/daemon.test.ts

@@ -0,0 +1,88 @@
+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/src/daemon.ts

@@ -15,17 +15,18 @@
  *
  * 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, type IncomingMessage, type ServerResponse } from 'node:http';
 import { WebSocketServer, WebSocket, type RawData } 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 ───────────────────────────────────────────────────────────
 
@@ -36,8 +37,6 @@ const pending = new Map<string, {
   reject: (error: Error) => void;
   timer: ReturnType<typeof setTimeout>;
 }>();
-let idleTimer: ReturnType<typeof setTimeout> | null = null;
-
 // Extension log ring buffer
 interface LogEntry { level: string; msg: string; ts: number; }
 const LOG_BUFFER_SIZE = 200;
@@ -50,13 +49,10 @@ function pushLog(entry: LogEntry): void {
 
 // ─── Idle auto-exit ──────────────────────────────────────────────────
 
-function resetIdleTimer(): void {
-  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 ─────────────────────────────────────────────────────
 
@@ -128,11 +124,18 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
   }
 
   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;
   }
@@ -153,8 +156,14 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
     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) {
@@ -212,6 +221,7 @@ wss.on('connection', (ws: WebSocket) => {
   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;
@@ -270,6 +280,7 @@ wss.on('connection', (ws: WebSocket) => {
     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);
@@ -284,6 +295,7 @@ wss.on('connection', (ws: WebSocket) => {
     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);
@@ -298,7 +310,7 @@ wss.on('connection', (ws: WebSocket) => {
 
 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: NodeJS.ErrnoException) => {

package/src/discovery.ts

@@ -11,15 +11,19 @@
 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 { type CliCommand, type InternalCliCommand, type Arg, Strategy, registerCommand } from './registry.js';
 import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
 import type { ManifestEntry } from './build-manifest.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*\(/;
 
@@ -33,6 +37,47 @@ function parseStrategy(rawStrategy: string | undefined, fallback: Strategy = Str
 
 import { isRecord } from './utils.js';
 
+function resolveHostRuntimeModulePath(moduleName: string): string {
+  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: string, content: string): Promise<void> {
+  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: string = USER_OPENCLI_DIR): Promise<void> {
+  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.
@@ -68,6 +113,7 @@ async function loadFromManifest(manifestPath: string, clisDir: string): Promise<
         const cmd: CliCommand = {
           site: entry.site,
           name: entry.name,
+          aliases: entry.aliases,
           description: entry.description ?? '',
           domain: entry.domain,
           strategy,
@@ -90,6 +136,7 @@ async function loadFromManifest(manifestPath: string, clisDir: string): Promise<
         const cmd: InternalCliCommand = {
           site: entry.site,
           name: entry.name,
+          aliases: entry.aliases,
           description: entry.description ?? '',
           domain: entry.domain,
           strategy,
@@ -163,6 +210,9 @@ async function registerYamlCli(filePath: string, defaultSite: string): Promise<v
     const cmd: CliCommand = {
       site,
       name,
+      aliases: isRecord(cliDef) && Array.isArray((cliDef as Record<string, unknown>).aliases)
+        ? ((cliDef as Record<string, unknown>).aliases as unknown[]).filter((value): value is string => typeof value === 'string')
+        : undefined,
       description: cliDef.description ?? '',
       domain: cliDef.domain,
       strategy,

package/src/electron-apps.test.ts

@@ -0,0 +1,50 @@
+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/src/electron-apps.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 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 const builtinApps: Record<string, ElectronAppEntry> = {
+  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?: Record<string, Omit<ElectronAppEntry, 'displayName'> & { displayName?: string }>,
+): Record<string, ElectronAppEntry> {
+  const merged = { ...builtinApps };
+  if (userApps) {
+    for (const [name, entry] of Object.entries(userApps)) {
+      if (!(name in merged)) {
+        merged[name] = entry as ElectronAppEntry;
+      }
+    }
+  }
+  return merged;
+}
+
+let _apps: Record<string, ElectronAppEntry> | null = null;
+
+function ensureLoaded(): Record<string, ElectronAppEntry> {
+  if (_apps) return _apps;
+
+  let userApps: Record<string, ElectronAppEntry> | undefined;
+  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) as { apps?: Record<string, ElectronAppEntry> };
+      userApps = parsed?.apps;
+    }
+  } catch {
+    // Silently ignore malformed user config
+  }
+
+  _apps = loadApps(userApps);
+  return _apps;
+}
+
+export function getElectronApp(site: string): ElectronAppEntry | undefined {
+  return ensureLoaded()[site];
+}
+
+export function isElectronApp(site: string): boolean {
+  return site in ensureLoaded();
+}
+
+/** Get all registered apps (builtin + user-defined). */
+export function getAllElectronApps(): Record<string, ElectronAppEntry> {
+  return ensureLoaded();
+}
+
+/** Reset loaded apps (for testing). */
+export function _resetRegistry(): void {
+  _apps = null;
+}

package/src/engine.test.ts

@@ -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';
@@ -78,6 +78,39 @@ 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', () => {
@@ -266,22 +299,25 @@ describe('executeCommand', () => {
     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();
   });
 });