@jackwener/opencli 1.5.6 → 1.5.7

package/src/commands/daemon.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('chalk', () => ({
+  default: {
+    green: (s: string) => s,
+    yellow: (s: string) => s,
+    red: (s: string) => s,
+    dim: (s: string) => 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: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  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/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,