@jackwener/opencli 1.1.0 → 1.2.0

package/src/doctor.test.ts

@@ -1,9 +1,36 @@
-import { describe, expect, it } from 'vitest';
-import { renderBrowserDoctorReport } from './doctor.js';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { mockCheckDaemonStatus, mockListSessions, mockConnect, mockClose } = vi.hoisted(() => ({
+  mockCheckDaemonStatus: vi.fn(),
+  mockListSessions: vi.fn(),
+  mockConnect: vi.fn(),
+  mockClose: vi.fn(),
+}));
+
+vi.mock('./browser/discover.js', () => ({
+  checkDaemonStatus: mockCheckDaemonStatus,
+}));
+
+vi.mock('./browser/daemon-client.js', () => ({
+  listSessions: mockListSessions,
+}));
+
+vi.mock('./browser/index.js', () => ({
+  BrowserBridge: class {
+    connect = mockConnect;
+    close = mockClose;
+  },
+}));
+
+import { renderBrowserDoctorReport, runBrowserDoctor } from './doctor.js';
 
 describe('doctor report rendering', () => {
   const strip = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, '');
 
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
   it('renders OK-style report when daemon and extension connected', () => {
     const text = strip(renderBrowserDoctorReport({
       daemonRunning: true,
@@ -59,4 +86,34 @@ describe('doctor report rendering', () => {
 
     expect(text).toContain('[SKIP] Connectivity: not tested (use --live)');
   });
+
+  it('reports consistent status when live check auto-starts the daemon', async () => {
+    // With the reordered flow, checkDaemonStatus is called only ONCE — after
+    // the connectivity check that may auto-start the daemon.
+    mockCheckDaemonStatus.mockResolvedValueOnce({ running: true, extensionConnected: false });
+    mockConnect.mockRejectedValueOnce(new Error(
+      'Daemon is running but the Browser Extension is not connected.\n' +
+      'Please install and enable the opencli Browser Bridge extension in Chrome.',
+    ));
+
+    const report = await runBrowserDoctor({ live: true });
+
+    // Status reflects the post-connectivity state (daemon running)
+    expect(report.daemonRunning).toBe(true);
+    expect(report.extensionConnected).toBe(false);
+    // checkDaemonStatus should only be called once
+    expect(mockCheckDaemonStatus).toHaveBeenCalledTimes(1);
+    // Should NOT report "daemon not running" since it IS running after live check
+    expect(report.issues).not.toContain(
+      expect.stringContaining('Daemon is not running'),
+    );
+    // Should report extension not connected
+    expect(report.issues).toEqual(expect.arrayContaining([
+      expect.stringContaining('Chrome extension is not connected'),
+    ]));
+    // Should report connectivity failure
+    expect(report.issues).toEqual(expect.arrayContaining([
+      expect.stringContaining('Browser connectivity test failed'),
+    ]));
+  });
 });

package/src/doctor.ts

@@ -51,12 +51,14 @@ export async function checkConnectivity(opts?: { timeout?: number }): Promise<Co
 }
 
 export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
-  const status = await checkDaemonStatus();
-
+  // Run the live connectivity check first — it may auto-start the daemon as a
+  // side-effect, so we read daemon status only *after* all side-effects settle.
   let connectivity: ConnectivityResult | undefined;
   if (opts.live) {
     connectivity = await checkConnectivity();
   }
+
+  const status = await checkDaemonStatus();
   const sessions = opts.sessions && status.running && status.extensionConnected
     ? await listSessions() as Array<{ workspace: string; windowId: number; tabCount: number; idleMsRemaining: number }>
     : undefined;

package/src/download/index.ts

@@ -2,7 +2,7 @@
  * Download utilities: HTTP downloads, yt-dlp wrapper, format conversion.
  */
 
-import { spawn, execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as https from 'node:https';
@@ -10,6 +10,7 @@ import * as http from 'node:http';
 import * as os from 'node:os';
 import { URL } from 'node:url';
 import type { ProgressBar } from './progress.js';
+import { isBinaryInstalled } from '../external.js';
 
 export interface DownloadOptions {
   cookies?: string;
@@ -36,68 +37,43 @@ export interface BrowserCookie {
   expirationDate?: number;
 }
 
-/**
- * Check if yt-dlp is available in PATH.
- */
+/** Check if yt-dlp is available in PATH. */
 export function checkYtdlp(): boolean {
-  try {
-    execSync('yt-dlp --version', { encoding: 'utf-8', stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
+  return isBinaryInstalled('yt-dlp');
 }
 
-/**
- * Check if ffmpeg is available in PATH.
- */
+/** Check if ffmpeg is available in PATH. */
 export function checkFfmpeg(): boolean {
-  try {
-    execSync('ffmpeg -version', { encoding: 'utf-8', stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
+  return isBinaryInstalled('ffmpeg');
 }
 
+/** Domains that host video content and can be downloaded via yt-dlp. */
+const VIDEO_PLATFORM_DOMAINS = [
+  'youtube.com', 'youtu.be', 'bilibili.com', 'twitter.com',
+  'x.com', 'tiktok.com', 'vimeo.com', 'twitch.tv',
+];
+
+const IMAGE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif']);
+const VIDEO_EXTENSIONS = new Set(['.mp4', '.webm', '.avi', '.mov', '.mkv', '.flv', '.m3u8', '.ts']);
+const DOC_EXTENSIONS = new Set(['.html', '.htm', '.json', '.xml', '.txt', '.md', '.markdown']);
+
 /**
  * Detect content type from URL and optional headers.
  */
 export function detectContentType(url: string, contentType?: string): 'image' | 'video' | 'document' | 'binary' {
-  // Check content-type header first
   if (contentType) {
     if (contentType.startsWith('image/')) return 'image';
     if (contentType.startsWith('video/')) return 'video';
     if (contentType.startsWith('text/') || contentType.includes('json') || contentType.includes('xml')) return 'document';
   }
 
-  // Detect from URL
   const urlLower = url.toLowerCase();
   const ext = path.extname(new URL(url).pathname).toLowerCase();
 
-  // Image extensions
-  if (['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif'].includes(ext)) {
-    return 'image';
-  }
-
-  // Video extensions
-  if (['.mp4', '.webm', '.avi', '.mov', '.mkv', '.flv', '.m3u8', '.ts'].includes(ext)) {
-    return 'video';
-  }
-
-  // Video platforms (need yt-dlp)
-  if (urlLower.includes('youtube.com') || urlLower.includes('youtu.be') ||
-      urlLower.includes('bilibili.com') || urlLower.includes('twitter.com') ||
-      urlLower.includes('x.com') || urlLower.includes('tiktok.com') ||
-      urlLower.includes('vimeo.com') || urlLower.includes('twitch.tv')) {
-    return 'video';
-  }
-
-  // Document extensions
-  if (['.html', '.htm', '.json', '.xml', '.txt', '.md', '.markdown'].includes(ext)) {
-    return 'document';
-  }
-
+  if (IMAGE_EXTENSIONS.has(ext)) return 'image';
+  if (VIDEO_EXTENSIONS.has(ext)) return 'video';
+  if (VIDEO_PLATFORM_DOMAINS.some(d => urlLower.includes(d))) return 'video';
+  if (DOC_EXTENSIONS.has(ext)) return 'document';
   return 'binary';
 }
 
@@ -106,16 +82,7 @@ export function detectContentType(url: string, contentType?: string): 'image' |
  */
 export function requiresYtdlp(url: string): boolean {
   const urlLower = url.toLowerCase();
-  return (
-    urlLower.includes('youtube.com') ||
-    urlLower.includes('youtu.be') ||
-    urlLower.includes('bilibili.com/video') ||
-    urlLower.includes('twitter.com') ||
-    urlLower.includes('x.com') ||
-    urlLower.includes('tiktok.com') ||
-    urlLower.includes('vimeo.com') ||
-    urlLower.includes('twitch.tv')
-  );
+  return VIDEO_PLATFORM_DOMAINS.some(d => urlLower.includes(d));
 }
 
 /**

package/src/engine.test.ts

@@ -1,16 +1,90 @@
-/**
- * Tests for engine.ts: CLI discovery and command execution.
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { discoverClis, executeCommand } from './engine.js';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { discoverClis, discoverPlugins, PLUGINS_DIR } from './discovery.js';
+import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
 describe('discoverClis', () => {
   it('handles non-existent directories gracefully', async () => {
     // Should not throw for missing directories
     await expect(discoverClis('/tmp/nonexistent-opencli-test-dir')).resolves.not.toThrow();
   });
+
+  it('imports only CLI command modules during filesystem discovery', async () => {
+    const tempRoot = await fs.promises.mkdtemp(path.join('/tmp', 'opencli-discovery-'));
+    const siteDir = path.join(tempRoot, 'temp-site');
+    const helperPath = path.join(siteDir, 'helper.ts');
+    const commandPath = path.join(siteDir, 'hello.ts');
+
+    try {
+      await fs.promises.mkdir(siteDir, { recursive: true });
+      await fs.promises.writeFile(helperPath, `
+globalThis.__opencli_helper_loaded__ = true;
+export const helper = true;
+`);
+      await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${path.join(process.cwd(), 'src', 'registry.ts')}';
+cli({
+  site: 'temp-site',
+  name: 'hello',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true }],
+});
+`);
+
+      delete (globalThis as any).__opencli_helper_loaded__;
+      await discoverClis(tempRoot);
+
+      expect((globalThis as any).__opencli_helper_loaded__).toBeUndefined();
+      expect(getRegistry().get('temp-site/hello')).toBeDefined();
+    } finally {
+      delete (globalThis as any).__opencli_helper_loaded__;
+      await fs.promises.rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('discoverPlugins', () => {
+  const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
+  const yamlPath = path.join(testPluginDir, 'greeting.yaml');
+
+  afterEach(async () => {
+    try { await fs.promises.rm(testPluginDir, { recursive: true }); } catch {}
+  });
+
+  it('discovers YAML plugins from ~/.opencli/plugins/', async () => {
+    // Create a simple YAML adapter in the plugins directory
+    await fs.promises.mkdir(testPluginDir, { recursive: true });
+    await fs.promises.writeFile(yamlPath, `
+site: __test-plugin__
+name: greeting
+description: Test plugin greeting
+strategy: public
+browser: false
+
+pipeline:
+  - evaluate: "() => [{ message: 'hello from plugin' }]"
+
+columns: [message]
+`);
+
+    await discoverPlugins();
+
+    const registry = getRegistry();
+    const cmd = registry.get('__test-plugin__/greeting');
+    expect(cmd).toBeDefined();
+    expect(cmd!.site).toBe('__test-plugin__');
+    expect(cmd!.name).toBe('greeting');
+    expect(cmd!.description).toBe('Test plugin greeting');
+  });
+
+  it('handles non-existent plugins directory gracefully', async () => {
+    // discoverPlugins should not throw if ~/.opencli/plugins/ does not exist
+    await expect(discoverPlugins()).resolves.not.toThrow();
+  });
 });
 
 describe('executeCommand', () => {
@@ -27,7 +101,7 @@ describe('executeCommand', () => {
       func: async (_page, kwargs) => [{ noteId: kwargs['note-id'] }],
     });
 
-    const result = await executeCommand(cmd, null, { 'note-id': 'abc123' });
+    const result = await executeCommand(cmd, { 'note-id': 'abc123' });
     expect(result).toEqual([{ noteId: 'abc123' }]);
   });
 
@@ -43,7 +117,7 @@ describe('executeCommand', () => {
       },
     });
 
-    const result = await executeCommand(cmd, null, { query: 'hello' });
+    const result = await executeCommand(cmd, { query: 'hello' });
     expect(result).toEqual([{ title: 'hello' }]);
   });
 
@@ -61,7 +135,7 @@ describe('executeCommand', () => {
     });
 
     // Pipeline commands require page for evaluate step, so we'll test the error path
-    await expect(executeCommand(cmd, null, {})).rejects.toThrow();
+    await expect(executeCommand(cmd, {})).rejects.toThrow();
   });
 
   it('throws for command with no func or pipeline', async () => {
@@ -72,7 +146,7 @@ describe('executeCommand', () => {
       browser: false,
     });
 
-    await expect(executeCommand(cmd, null, {})).rejects.toThrow('has no func or pipeline');
+    await expect(executeCommand(cmd, {})).rejects.toThrow('has no func or pipeline');
   });
 
   it('passes debug flag to func', async () => {
@@ -88,7 +162,7 @@ describe('executeCommand', () => {
       },
     });
 
-    await executeCommand(cmd, null, {}, true);
+    await executeCommand(cmd, {}, true);
     expect(receivedDebug).toBe(true);
   });
 });

package/src/execution.ts

@@ -0,0 +1,164 @@
+/**
+ * Command execution: validates args, manages browser sessions, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. Browser session lifecycle (if needed)
+ * 3. Domain pre-navigation for cookie/header strategies
+ * 4. Timeout enforcement
+ * 5. Lazy-loading of TS modules from manifest
+ */
+
+import { type CliCommand, type InternalCliCommand, type Arg, Strategy, getRegistry, fullName } from './registry.js';
+import type { IPage } from './types.js';
+import { pathToFileURL } from 'node:url';
+import { executePipeline } from './pipeline/index.js';
+import { AdapterLoadError } from './errors.js';
+import { shouldUseBrowserSession } from './capabilityRouting.js';
+import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
+
+/** Set of TS module paths that have been loaded */
+const _loadedModules = new Set<string>();
+type CommandArgs = Record<string, unknown>;
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Validates and coerces arguments based on the command's Arg definitions.
+ */
+export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {
+  const result: CommandArgs = { ...kwargs };
+
+  for (const argDef of cmdArgs) {
+    const val = result[argDef.name];
+    
+    // 1. Check required
+    if (argDef.required && (val === undefined || val === null || val === '')) {
+      throw new Error(`Argument "${argDef.name}" is required.\n${argDef.help ? `Hint: ${argDef.help}` : ''}`);
+    }
+
+    if (val !== undefined && val !== null) {
+      // 2. Type coercion
+      if (argDef.type === 'int' || argDef.type === 'number') {
+        const num = Number(val);
+        if (Number.isNaN(num)) {
+          throw new Error(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+        }
+        result[argDef.name] = num;
+      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {
+        if (typeof val === 'string') {
+          const lower = val.toLowerCase();
+          if (lower === 'true' || lower === '1') result[argDef.name] = true;
+          else if (lower === 'false' || lower === '0') result[argDef.name] = false;
+          else throw new Error(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+        } else {
+          result[argDef.name] = Boolean(val);
+        }
+      }
+
+      // 3. Choices validation
+      const coercedVal = result[argDef.name];
+      if (argDef.choices && argDef.choices.length > 0) {
+        if (!argDef.choices.map(String).includes(String(coercedVal))) {
+          throw new Error(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+        }
+      }
+    } else if (argDef.default !== undefined) {
+      result[argDef.name] = argDef.default;
+    }
+  }
+  return result;
+}
+
+/**
+ * Run a command's func or pipeline against a page.
+ */
+async function runCommand(
+  cmd: CliCommand,
+  page: IPage | null,
+  kwargs: CommandArgs,
+  debug: boolean,
+): Promise<unknown> {
+  // Lazy-load TS module on first execution (manifest fast-path)
+  const internal = cmd as InternalCliCommand;
+  if (internal._lazy && internal._modulePath) {
+    const modulePath = internal._modulePath;
+    if (!_loadedModules.has(modulePath)) {
+      try {
+        await import(pathToFileURL(modulePath).href);
+        _loadedModules.add(modulePath);
+      } catch (err) {
+        throw new AdapterLoadError(
+          `Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`,
+          'Check that the adapter file exists and has no syntax errors.',
+        );
+      }
+    }
+    // After loading, the module's cli() call will have updated the registry.
+    const updated = getRegistry().get(fullName(cmd));
+    if (updated?.func) return updated.func(page!, kwargs, debug);
+    if (updated?.pipeline) return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+  }
+
+  if (cmd.func) return cmd.func(page!, kwargs, debug);
+  if (cmd.pipeline) return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
+  throw new Error(`Command ${fullName(cmd)} has no func or pipeline`);
+}
+
+/**
+ * Resolve the pre-navigation URL for a command, or null to skip.
+ *
+ * COOKIE/HEADER strategies need the browser on the target domain so
+ * `fetch(url, { credentials: 'include' })` carries cookies.
+ * Adapters that handle their own navigation set `navigateBefore: false`.
+ */
+function resolvePreNav(cmd: CliCommand): string | null {
+  if (cmd.navigateBefore === false) return null;
+  if (typeof cmd.navigateBefore === 'string') return cmd.navigateBefore;
+
+  // Default: pre-navigate for COOKIE/HEADER strategies with a domain
+  if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
+    return `https://${cmd.domain}`;
+  }
+  return null;
+}
+
+/**
+ * Execute a CLI command. Automatically manages browser sessions when needed.
+ *
+ * This is the unified entry point — callers don't need to care about
+ * whether the command requires a browser or not.
+ */
+export async function executeCommand(
+  cmd: CliCommand,
+  rawKwargs: CommandArgs,
+  debug: boolean = false,
+): Promise<unknown> {
+  let kwargs: CommandArgs;
+  try {
+    kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+  } catch (err) {
+    throw new Error(`[Argument Validation Error]\n${getErrorMessage(err)}`);
+  }
+
+  if (shouldUseBrowserSession(cmd)) {
+    const BrowserFactory = getBrowserFactory();
+    return browserSession(BrowserFactory, async (page) => {
+      // Pre-navigate to target domain for cookie/header context if needed.
+      // Each adapter controls this via `navigateBefore` (see CliCommand docs).
+      const preNavUrl = resolvePreNav(cmd);
+      if (preNavUrl) {
+        try { await page.goto(preNavUrl); await page.wait(2); } catch {}
+      }
+      return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+        timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+        label: fullName(cmd),
+      });
+    }, { workspace: `site:${cmd.site}` });
+  }
+
+  // Non-browser commands run directly
+  return runCommand(cmd, null, kwargs, debug);
+}