@jackwener/opencli 1.0.6 → 1.1.1

package/src/clis/youtube/video.ts

@@ -11,7 +11,7 @@ cli({
   domain: 'www.youtube.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'url', required: true, help: 'YouTube video URL or video ID' },
+    { name: 'url', required: true, positional: true, help: 'YouTube video URL or video ID' },
   ],
   columns: ['field', 'value'],
   func: async (page, kwargs) => {

package/src/clis/zhihu/download.ts

@@ -92,7 +92,7 @@ cli({
   domain: 'zhuanlan.zhihu.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'url', required: true, help: 'Article URL (zhuanlan.zhihu.com/p/xxx)' },
+    { name: 'url', required: true, positional: true, help: 'Article URL (zhuanlan.zhihu.com/p/xxx)' },
     { name: 'output', default: './zhihu-articles', help: 'Output directory' },
     { name: 'download-images', type: 'boolean', default: false, help: 'Download images locally' },
   ],
@@ -104,7 +104,6 @@ cli({
 
     // Navigate to article page
     await page.goto(url);
-    await page.wait(3);
 
     // Extract article content
     const data = await page.evaluate(`

package/src/clis/zhihu/question.ts

@@ -7,7 +7,7 @@ cli({
   domain: 'www.zhihu.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'id', required: true, help: 'Question ID (numeric)' },
+    { name: 'id', required: true, positional: true, help: 'Question ID (numeric)' },
     { name: 'limit', type: 'int', default: 5, help: 'Number of answers' },
   ],
   columns: ['rank', 'author', 'votes', 'content'],

package/src/clis/zhihu/search.yaml

@@ -4,10 +4,11 @@ description: 知乎搜索
 domain: www.zhihu.com
 
 args:
-  keyword:
+  query:
+    positional: true
     type: str
     required: true
-    description: Search keyword
+    description: Search query
   limit:
     type: int
     default: 10
@@ -19,7 +20,7 @@ pipeline:
   - evaluate: |
       (async () => {
         const strip = (html) => (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/<em>/g, '').replace(/<\/em>/g, '').trim();
-        const keyword = ${{ args.keyword | json }};
+        const keyword = ${{ args.query | json }};
         const limit = ${{ args.limit }};
         const res = await fetch('https://www.zhihu.com/api/v4/search_v3?q=' + encodeURIComponent(keyword) + '&t=general&offset=0&limit=' + limit, {
           credentials: 'include'

package/src/commanderAdapter.ts

@@ -0,0 +1,113 @@
+/**
+ * Commander adapter: bridges Registry commands to Commander subcommands.
+ *
+ * This is a THIN adapter — it only handles:
+ * 1. Commander arg/option registration
+ * 2. Collecting kwargs from Commander's action args
+ * 3. Calling executeCommand (which handles browser sessions, validation, etc.)
+ * 4. Rendering output and errors
+ *
+ * All execution logic lives in execution.ts.
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { type CliCommand, fullName, getRegistry } from './registry.js';
+import { formatRegistryHelpText } from './serialization.js';
+import { render as renderOutput } from './output.js';
+import { executeCommand } from './execution.js';
+import { CliError } from './errors.js';
+
+/**
+ * Register a single CliCommand as a Commander subcommand.
+ */
+export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void {
+  if (siteCmd.commands.some((c: Command) => c.name() === cmd.name)) return;
+
+  const subCmd = siteCmd.command(cmd.name).description(cmd.description);
+
+  // Register positional args first, then named options
+  const positionalArgs: typeof cmd.args = [];
+  for (const arg of cmd.args) {
+    if (arg.positional) {
+      const bracket = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+      subCmd.argument(bracket, arg.help ?? '');
+      positionalArgs.push(arg);
+    } else {
+      const flag = arg.required ? `--${arg.name} <value>` : `--${arg.name} [value]`;
+      if (arg.required) subCmd.requiredOption(flag, arg.help ?? '');
+      else if (arg.default != null) subCmd.option(flag, arg.help ?? '', String(arg.default));
+      else subCmd.option(flag, arg.help ?? '');
+    }
+  }
+  subCmd
+    .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
+    .option('-v, --verbose', 'Debug output', false);
+
+  subCmd.addHelpText('after', formatRegistryHelpText(cmd));
+
+  subCmd.action(async (...actionArgs: any[]) => {
+    const actionOpts = actionArgs[positionalArgs.length] ?? {};
+    const startTime = Date.now();
+
+    // ── Collect kwargs ──────────────────────────────────────────────────
+    const kwargs: Record<string, any> = {};
+    for (let i = 0; i < positionalArgs.length; i++) {
+      const v = actionArgs[i];
+      if (v !== undefined) kwargs[positionalArgs[i].name] = v;
+    }
+    for (const arg of cmd.args) {
+      if (arg.positional) continue;
+      const camelName = arg.name.replace(/-([a-z])/g, (_m, ch: string) => ch.toUpperCase());
+      const v = actionOpts[arg.name] ?? actionOpts[camelName];
+      if (v !== undefined) kwargs[arg.name] = v;
+    }
+
+    // ── Execute + render ────────────────────────────────────────────────
+    try {
+      if (actionOpts.verbose) process.env.OPENCLI_VERBOSE = '1';
+
+      const result = await executeCommand(cmd, kwargs, actionOpts.verbose);
+
+      if (actionOpts.verbose && (!result || (Array.isArray(result) && result.length === 0))) {
+        console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
+      }
+      const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
+      renderOutput(result, {
+        fmt: actionOpts.format,
+        columns: resolved.columns,
+        title: `${resolved.site}/${resolved.name}`,
+        elapsed: (Date.now() - startTime) / 1000,
+        source: fullName(resolved),
+        footerExtra: resolved.footerExtra?.(kwargs),
+      });
+    } catch (err: any) {
+      if (err instanceof CliError) {
+        console.error(chalk.red(`Error [${err.code}]: ${err.message}`));
+        if (err.hint) console.error(chalk.yellow(`Hint: ${err.hint}`));
+      } else if (actionOpts.verbose && err.stack) {
+        console.error(chalk.red(err.stack));
+      } else {
+        console.error(chalk.red(`Error: ${err.message ?? err}`));
+      }
+      process.exitCode = 1;
+    }
+  });
+}
+
+/**
+ * Register all commands from the registry onto a Commander program.
+ */
+export function registerAllCommands(
+  program: Command,
+  siteGroups: Map<string, Command>,
+): void {
+  for (const [, cmd] of getRegistry()) {
+    let siteCmd = siteGroups.get(cmd.site);
+    if (!siteCmd) {
+      siteCmd = program.command(cmd.site).description(`${cmd.site} commands`);
+      siteGroups.set(cmd.site, siteCmd);
+    }
+    registerCommandToProgram(siteCmd, cmd);
+  }
+}

package/src/daemon.ts

@@ -12,7 +12,7 @@
  */
 
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
-import { WebSocketServer, WebSocket } from 'ws';
+import { WebSocketServer, WebSocket, type RawData } from 'ws';
 
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? '19825', 10);
 const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
@@ -138,11 +138,11 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
 const httpServer = createServer((req, res) => { handleRequest(req, res).catch(() => { res.writeHead(500); res.end(); }); });
 const wss = new WebSocketServer({ server: httpServer, path: '/ext' });
 
-wss.on('connection', (ws) => {
+wss.on('connection', (ws: WebSocket) => {
   console.error('[daemon] Extension connected');
   extensionWs = ws;
 
-  ws.on('message', (data) => {
+  ws.on('message', (data: RawData) => {
     try {
       const msg = JSON.parse(data.toString());
 

package/src/{engine.ts → discovery.ts}

@@ -12,13 +12,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
 import { type CliCommand, type InternalCliCommand, type Arg, Strategy, registerCommand } from './registry.js';
-import type { IPage } from './types.js';
-import { executePipeline } from './pipeline.js';
 import { log } from './logger.js';
-import { AdapterLoadError } from './errors.js';
-
-/** Set of TS module paths that have been loaded */
-const _loadedModules = new Set<string>();
 
 /**
  * Discover and register CLI commands.
@@ -145,6 +139,7 @@ async function registerYamlCli(filePath: string, defaultSite: string): Promise<v
           type: argDef?.type ?? 'str',
           default: argDef?.default,
           required: argDef?.required ?? false,
+          positional: argDef?.positional ?? false,
           help: argDef?.description ?? argDef?.help ?? '',
           choices: argDef?.choices,
         });
@@ -170,105 +165,3 @@ async function registerYamlCli(filePath: string, defaultSite: string): Promise<v
     log.warn(`Failed to load ${filePath}: ${err.message}`);
   }
 }
-
-/**
- * Validates and coerces arguments based on the command's Arg definitions.
- */
-function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any>): Record<string, any> {
-  const result: Record<string, any> = { ...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) {
-        // Only stringent check for string/number types against choices array
-        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) {
-      // Set default if value is missing
-      result[argDef.name] = argDef.default;
-    }
-  }
-  return result;
-}
-
-/**
- * Execute a CLI command. Handles lazy-loading of TS modules.
- */
-export async function executeCommand(
-  cmd: CliCommand,
-  page: IPage | null,
-  rawKwargs: Record<string, any>,
-  debug: boolean = false,
-): Promise<any> {
-  let kwargs: Record<string, any>;
-  try {
-    kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
-  } catch (err: any) {
-    // Re-throw validation errors clearly
-    throw new Error(`[Argument Validation Error]\n${err.message}`);
-  }
-
-  // Lazy-load TS module on first execution
-  const internal = cmd as InternalCliCommand;
-  if (internal._lazy && internal._modulePath) {
-    const modulePath = internal._modulePath;
-    if (!_loadedModules.has(modulePath)) {
-      try {
-        await import(`file://${modulePath}`);
-        _loadedModules.add(modulePath);
-      } catch (err: any) {
-        throw new AdapterLoadError(
-          `Failed to load adapter module ${modulePath}: ${err.message}`,
-          'Check that the adapter file exists and has no syntax errors.',
-        );
-      }
-    }
-    // After loading, the module's cli() call will have updated the registry
-    // with the real func/pipeline. Re-fetch the command.
-    const { getRegistry, fullName } = await import('./registry.js');
-    const updated = getRegistry().get(fullName(cmd));
-    if (updated && updated.func) {
-      return updated.func(page!, kwargs, debug);
-    }
-    if (updated && 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 ${cmd.site}/${cmd.name} has no func or pipeline`);
-}

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,9 +1,10 @@
 /**
- * Tests for engine.ts: CLI discovery and command execution.
+ * Tests for discovery and execution modules.
  */
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { discoverClis, executeCommand } from './engine.js';
+import { discoverClis } from './discovery.js';
+import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
 
 describe('discoverClis', () => {
@@ -27,7 +28,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 +44,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 +62,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 +73,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 +89,7 @@ describe('executeCommand', () => {
       },
     });
 
-    await executeCommand(cmd, null, {}, true);
+    await executeCommand(cmd, {}, true);
     expect(receivedDebug).toBe(true);
   });
 });

package/src/execution.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 { executePipeline } from './pipeline.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>();
+
+/**
+ * Validates and coerces arguments based on the command's Arg definitions.
+ */
+export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = { ...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: Record<string, any>,
+  debug: boolean,
+): Promise<any> {
+  // 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(`file://${modulePath}`);
+        _loadedModules.add(modulePath);
+      } catch (err: any) {
+        throw new AdapterLoadError(
+          `Failed to load adapter module ${modulePath}: ${err.message}`,
+          '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`);
+}
+
+/**
+ * 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: Record<string, any>,
+  debug: boolean = false,
+): Promise<any> {
+  let kwargs: Record<string, any>;
+  try {
+    kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+  } catch (err: any) {
+    throw new Error(`[Argument Validation Error]\n${err.message}`);
+  }
+
+  if (shouldUseBrowserSession(cmd)) {
+    const BrowserFactory = getBrowserFactory();
+    return browserSession(BrowserFactory, async (page) => {
+      // Cookie/header strategies require same-origin context for credentialed fetch.
+      if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
+        try { await page.goto(`https://${cmd.domain}`); 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);
+}