@jackwener/opencli 1.1.0 → 1.2.0

package/dist/{engine.js → discovery.js}

@@ -8,14 +8,27 @@
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
 import { Strategy, registerCommand } from './registry.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();
+/** Plugins directory: ~/.opencli/plugins/ */
+export const PLUGINS_DIR = path.join(os.homedir(), '.opencli', 'plugins');
+const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
+    if (!rawStrategy)
+        return fallback;
+    const key = rawStrategy.toUpperCase();
+    return Strategy[key] ?? fallback;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
@@ -47,7 +60,7 @@ async function loadFromManifest(manifestPath, clisDir) {
         for (const entry of manifest) {
             if (entry.type === 'yaml') {
                 // YAML pipelines fully inlined in manifest — register directly
-                const strategy = Strategy[entry.strategy.toUpperCase()] ?? Strategy.COOKIE;
+                const strategy = parseStrategy(entry.strategy);
                 const cmd = {
                     site: entry.site,
                     name: entry.name,
@@ -60,13 +73,14 @@ async function loadFromManifest(manifestPath, clisDir) {
                     pipeline: entry.pipeline,
                     timeoutSeconds: entry.timeout,
                     source: `manifest:${entry.site}/${entry.name}`,
+                    navigateBefore: entry.navigateBefore,
                 };
                 registerCommand(cmd);
             }
             else if (entry.type === 'ts' && entry.modulePath) {
                 // TS adapters: register a lightweight stub.
                 // The actual module is loaded lazily on first executeCommand().
-                const strategy = Strategy[(entry.strategy ?? 'cookie').toUpperCase()] ?? Strategy.COOKIE;
+                const strategy = parseStrategy(entry.strategy ?? 'cookie');
                 const modulePath = path.resolve(clisDir, entry.modulePath);
                 const cmd = {
                     site: entry.site,
@@ -79,6 +93,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                     columns: entry.columns,
                     timeoutSeconds: entry.timeout,
                     source: modulePath,
+                    navigateBefore: entry.navigateBefore,
                     _lazy: true,
                     _modulePath: modulePath,
                 };
@@ -87,7 +102,7 @@ async function loadFromManifest(manifestPath, clisDir) {
         }
     }
     catch (err) {
-        log.warn(`Failed to load manifest ${manifestPath}: ${err.message}`);
+        log.warn(`Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
     }
 }
 /**
@@ -115,8 +130,10 @@ async function discoverClisFromFs(dir) {
             }
             else if ((file.endsWith('.js') && !file.endsWith('.d.js')) ||
                 (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))) {
-                promises.push(import(`file://${filePath}`).catch((err) => {
-                    log.warn(`Failed to load module ${filePath}: ${err.message}`);
+                if (!(await isCliModule(filePath)))
+                    continue;
+                promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                    log.warn(`Failed to load module ${filePath}: ${getErrorMessage(err)}`);
                 }));
             }
         }
@@ -127,21 +144,23 @@ async function registerYamlCli(filePath, defaultSite) {
     try {
         const raw = await fs.promises.readFile(filePath, 'utf-8');
         const def = yaml.load(raw);
-        if (!def || typeof def !== 'object')
+        if (!isRecord(def))
             return;
-        const site = def.site ?? defaultSite;
-        const name = def.name ?? path.basename(filePath, path.extname(filePath));
-        const strategyStr = def.strategy ?? (def.browser === false ? 'public' : 'cookie');
-        const strategy = Strategy[strategyStr.toUpperCase()] ?? Strategy.COOKIE;
-        const browser = def.browser ?? (strategy !== Strategy.PUBLIC);
+        const cliDef = def;
+        const site = cliDef.site ?? defaultSite;
+        const name = cliDef.name ?? path.basename(filePath, path.extname(filePath));
+        const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
+        const strategy = parseStrategy(strategyStr);
+        const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
         const args = [];
-        if (def.args && typeof def.args === 'object') {
-            for (const [argName, argDef] of Object.entries(def.args)) {
+        if (cliDef.args && typeof cliDef.args === 'object') {
+            for (const [argName, argDef] of Object.entries(cliDef.args)) {
                 args.push({
                     name: argName,
                     type: argDef?.type ?? 'str',
                     default: argDef?.default,
                     required: argDef?.required ?? false,
+                    positional: argDef?.positional ?? false,
                     help: argDef?.description ?? argDef?.help ?? '',
                     choices: argDef?.choices,
                 });
@@ -150,113 +169,83 @@ async function registerYamlCli(filePath, defaultSite) {
         const cmd = {
             site,
             name,
-            description: def.description ?? '',
-            domain: def.domain,
+            description: cliDef.description ?? '',
+            domain: cliDef.domain,
             strategy,
             browser,
             args,
-            columns: def.columns,
-            pipeline: def.pipeline,
-            timeoutSeconds: def.timeout,
+            columns: cliDef.columns,
+            pipeline: cliDef.pipeline,
+            timeoutSeconds: cliDef.timeout,
             source: filePath,
+            navigateBefore: cliDef.navigateBefore,
         };
         registerCommand(cmd);
     }
     catch (err) {
-        log.warn(`Failed to load ${filePath}: ${err.message}`);
+        log.warn(`Failed to load ${filePath}: ${getErrorMessage(err)}`);
     }
 }
 /**
- * Validates and coerces arguments based on the command's Arg definitions.
+ * Discover and register plugins from ~/.opencli/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
  */
-function coerceAndValidateArgs(cmdArgs, kwargs) {
-    const result = { ...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;
-        }
+export async function discoverPlugins() {
+    try {
+        await fs.promises.access(PLUGINS_DIR);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        await discoverPluginDir(path.join(PLUGINS_DIR, entry.name), entry.name);
     }
-    return result;
 }
 /**
- * Execute a CLI command. Handles lazy-loading of TS modules.
+ * Flat scan: read yaml/ts files directly in a plugin directory.
+ * Unlike discoverClisFromFs, this does NOT expect nested site subdirectories.
  */
-export async function executeCommand(cmd, page, rawKwargs, debug = false) {
-    let kwargs;
-    try {
-        kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
-    }
-    catch (err) {
-        // Re-throw validation errors clearly
-        throw new Error(`[Argument Validation Error]\n${err.message}`);
-    }
-    // Lazy-load TS module on first execution
-    const internal = cmd;
-    if (internal._lazy && internal._modulePath) {
-        const modulePath = internal._modulePath;
-        if (!_loadedModules.has(modulePath)) {
-            try {
-                await import(`file://${modulePath}`);
-                _loadedModules.add(modulePath);
-            }
-            catch (err) {
-                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${err.message}`, 'Check that the adapter file exists and has no syntax errors.');
-            }
+async function discoverPluginDir(dir, site) {
+    const files = await fs.promises.readdir(dir);
+    const fileSet = new Set(files);
+    const promises = [];
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+            promises.push(registerYamlCli(filePath, site));
         }
-        // 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);
+        else if (file.endsWith('.js') && !file.endsWith('.d.js')) {
+            if (!(await isCliModule(filePath)))
+                continue;
+            promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+            }));
         }
-        if (updated && updated.pipeline) {
-            return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+        else if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
+            // Skip .ts if a compiled .js sibling exists (production mode can't load .ts)
+            const jsFile = file.replace(/\.ts$/, '.js');
+            if (fileSet.has(jsFile))
+                continue;
+            if (!(await isCliModule(filePath)))
+                continue;
+            promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+            }));
         }
     }
-    if (cmd.func) {
-        return cmd.func(page, kwargs, debug);
+    await Promise.all(promises);
+}
+async function isCliModule(filePath) {
+    try {
+        const source = await fs.promises.readFile(filePath, 'utf-8');
+        return CLI_MODULE_PATTERN.test(source);
     }
-    if (cmd.pipeline) {
-        return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
+    catch (err) {
+        log.warn(`Failed to inspect module ${filePath}: ${getErrorMessage(err)}`);
+        return false;
     }
-    throw new Error(`Command ${cmd.site}/${cmd.name} has no func or pipeline`);
 }

package/dist/doctor.js

@@ -26,11 +26,13 @@ export async function checkConnectivity(opts) {
     }
 }
 export async function runBrowserDoctor(opts = {}) {
-    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;
     if (opts.live) {
         connectivity = await checkConnectivity();
     }
+    const status = await checkDaemonStatus();
     const sessions = opts.sessions && status.running && status.extensionConnected
         ? await listSessions()
         : undefined;

package/dist/doctor.test.js

@@ -1,7 +1,28 @@
-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) => 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,
@@ -48,4 +69,27 @@ 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/dist/download/index.d.ts

@@ -23,13 +23,9 @@ export interface BrowserCookie {
     httpOnly?: boolean;
     expirationDate?: number;
 }
-/**
- * Check if yt-dlp is available in PATH.
- */
+/** Check if yt-dlp is available in PATH. */
 export declare function checkYtdlp(): boolean;
-/**
- * Check if ffmpeg is available in PATH.
- */
+/** Check if ffmpeg is available in PATH. */
 export declare function checkFfmpeg(): boolean;
 /**
  * Detect content type from URL and optional headers.

package/dist/download/index.js

@@ -1,42 +1,34 @@
 /**
  * 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';
 import * as http from 'node:http';
 import * as os from 'node:os';
 import { URL } from 'node:url';
-/**
- * Check if yt-dlp is available in PATH.
- */
+import { isBinaryInstalled } from '../external.js';
+/** Check if yt-dlp is available in PATH. */
 export function checkYtdlp() {
-    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() {
-    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, contentType) {
-    // Check content-type header first
     if (contentType) {
         if (contentType.startsWith('image/'))
             return 'image';
@@ -45,28 +37,16 @@ export function detectContentType(url, contentType) {
         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)) {
+    if (IMAGE_EXTENSIONS.has(ext))
         return 'image';
-    }
-    // Video extensions
-    if (['.mp4', '.webm', '.avi', '.mov', '.mkv', '.flv', '.m3u8', '.ts'].includes(ext)) {
+    if (VIDEO_EXTENSIONS.has(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')) {
+    if (VIDEO_PLATFORM_DOMAINS.some(d => urlLower.includes(d)))
         return 'video';
-    }
-    // Document extensions
-    if (['.html', '.htm', '.json', '.xml', '.txt', '.md', '.markdown'].includes(ext)) {
+    if (DOC_EXTENSIONS.has(ext))
         return 'document';
-    }
     return 'binary';
 }
 /**
@@ -74,14 +54,7 @@ export function detectContentType(url, contentType) {
  */
 export function requiresYtdlp(url) {
     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));
 }
 /**
  * HTTP download with progress callback.

package/dist/engine.test.d.ts

@@ -1,4 +1 @@
-/**
- * Tests for engine.ts: CLI discovery and command execution.
- */
 export {};

package/dist/engine.test.js

@@ -1,14 +1,83 @@
-/**
- * Tests for engine.ts: CLI discovery and command execution.
- */
-import { describe, it, expect } from 'vitest';
-import { discoverClis, executeCommand } from './engine.js';
-import { cli, Strategy } from './registry.js';
+import { describe, it, expect, 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.__opencli_helper_loaded__;
+            await discoverClis(tempRoot);
+            expect(globalThis.__opencli_helper_loaded__).toBeUndefined();
+            expect(getRegistry().get('temp-site/hello')).toBeDefined();
+        }
+        finally {
+            delete globalThis.__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', () => {
     it('accepts kebab-case option names after Commander camelCases them', async () => {
@@ -23,7 +92,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' }]);
     });
     it('executes a command with func', async () => {
@@ -37,7 +106,7 @@ describe('executeCommand', () => {
                 return [{ title: kwargs.query ?? 'default' }];
             },
         });
-        const result = await executeCommand(cmd, null, { query: 'hello' });
+        const result = await executeCommand(cmd, { query: 'hello' });
         expect(result).toEqual([{ title: 'hello' }]);
     });
     it('executes a command with pipeline', async () => {
@@ -53,7 +122,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 () => {
         const cmd = cli({
@@ -62,7 +131,7 @@ describe('executeCommand', () => {
             description: 'empty command',
             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 () => {
         let receivedDebug = false;
@@ -76,7 +145,7 @@ describe('executeCommand', () => {
                 return [];
             },
         });
-        await executeCommand(cmd, null, {}, true);
+        await executeCommand(cmd, {}, true);
         expect(receivedDebug).toBe(true);
     });
 });

package/dist/execution.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 Arg } from './registry.js';
+type CommandArgs = Record<string, unknown>;
+/**
+ * Validates and coerces arguments based on the command's Arg definitions.
+ */
+export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
+/**
+ * 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 declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean): Promise<unknown>;
+export {};