@jackwener/opencli 1.0.6 → 1.1.1

package/dist/clis/xiaohongshu/creator-profile.js

@@ -19,7 +19,6 @@ cli({
     columns: ['field', 'value'],
     func: async (page, _kwargs) => {
         await page.goto('https://creator.xiaohongshu.com/new/home');
-        await page.wait(3);
         const data = await page.evaluate(`
       async () => {
         try {

package/dist/clis/xiaohongshu/creator-stats.js

@@ -29,7 +29,6 @@ cli({
         const period = kwargs.period || 'seven';
         // Navigate to creator center for cookie context
         await page.goto('https://creator.xiaohongshu.com/new/home');
-        await page.wait(3);
         const data = await page.evaluate(`
       async () => {
         try {

package/dist/clis/xiaohongshu/download.js

@@ -16,16 +16,15 @@ cli({
     domain: 'www.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     args: [
-        { name: 'note_id', required: true, help: 'Note ID (from URL)' },
+        { name: 'note-id', required: true, help: 'Note ID (from URL)' },
         { name: 'output', default: './xiaohongshu-downloads', help: 'Output directory' },
     ],
     columns: ['index', 'type', 'status', 'size'],
     func: async (page, kwargs) => {
-        const noteId = kwargs.note_id;
+        const noteId = kwargs['note-id'];
         const output = kwargs.output;
         // Navigate to note page
         await page.goto(`https://www.xiaohongshu.com/explore/${noteId}`);
-        await page.wait(3);
         // Extract note info and media URLs
         const data = await page.evaluate(`
       (() => {

package/dist/clis/xiaohongshu/feed.yaml

@@ -15,7 +15,6 @@ columns: [title, author, likes, type, url]
 
 pipeline:
   - navigate: https://www.xiaohongshu.com/explore
-  - wait: 3
   - tap:
       store: feed
       action: fetchFeeds

package/dist/clis/xiaohongshu/notifications.yaml

@@ -19,7 +19,6 @@ columns: [rank, user, action, content, note, time]
 
 pipeline:
   - navigate: https://www.xiaohongshu.com/notification
-  - wait: 3
   - tap:
       store: notification
       action: getNotification

package/dist/clis/xiaohongshu/search.js

@@ -13,12 +13,12 @@ cli({
     domain: 'www.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     args: [
-        { name: 'keyword', required: true, help: 'Search keyword' },
+        { name: 'query', required: true, positional: true, help: 'Search keyword' },
         { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
     ],
     columns: ['rank', 'title', 'author', 'likes'],
     func: async (page, kwargs) => {
-        const keyword = encodeURIComponent(kwargs.keyword);
+        const keyword = encodeURIComponent(kwargs.query);
         await page.goto(`https://www.xiaohongshu.com/search_result?keyword=${keyword}&source=web_search_result_notes`);
         await page.wait(3);
         // Scroll a couple of times to load more results

package/dist/clis/xiaohongshu/user.js

@@ -27,7 +27,7 @@ cli({
     strategy: Strategy.COOKIE,
     browser: true,
     args: [
-        { name: 'id', type: 'string', required: true, help: 'User id or profile URL' },
+        { name: 'id', type: 'string', required: true, positional: true, help: 'User id or profile URL' },
         { name: 'limit', type: 'int', default: 15, help: 'Number of notes to return' },
     ],
     columns: ['id', 'title', 'type', 'likes', 'url'],
@@ -35,7 +35,6 @@ cli({
         const userId = normalizeXhsUserId(String(kwargs.id));
         const limit = Math.max(1, Number(kwargs.limit ?? 15));
         await page.goto(`https://www.xiaohongshu.com/user/profile/${userId}`);
-        await page.wait(3);
         let snapshot = await readUserSnapshot(page);
         let results = extractXhsUserNotes(snapshot ?? {}, userId);
         let previousCount = results.length;

package/dist/clis/yahoo-finance/quote.js

@@ -16,7 +16,6 @@ cli({
     func: async (page, kwargs) => {
         const symbol = kwargs.symbol.toUpperCase().trim();
         await page.goto(`https://finance.yahoo.com/quote/${encodeURIComponent(symbol)}/`);
-        await page.wait(3);
         const data = await page.evaluate(`
       (async () => {
         const sym = '${symbol}';

package/dist/clis/youtube/search.js

@@ -10,7 +10,7 @@ cli({
     domain: 'www.youtube.com',
     strategy: Strategy.COOKIE,
     args: [
-        { name: 'query', required: true, help: 'Search query' },
+        { name: 'query', required: true, positional: true, help: 'Search query' },
         { name: 'limit', type: 'int', default: 20, help: 'Max results (max 50)' },
     ],
     columns: ['rank', 'title', 'channel', 'views', 'duration', 'url'],

package/dist/clis/youtube/transcript.js

@@ -19,7 +19,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' },
         { name: 'lang', required: false, help: 'Language code (e.g. en, zh-Hans). Omit to auto-select' },
         { name: 'mode', required: false, default: 'grouped', help: 'Output mode: grouped (readable paragraphs) or raw (every segment)' },
     ],

package/dist/clis/youtube/video.js

@@ -10,7 +10,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/dist/clis/zhihu/download.js

@@ -72,7 +72,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' },
     ],
@@ -83,7 +83,6 @@ cli({
         const downloadImages = kwargs['download-images'];
         // Navigate to article page
         await page.goto(url);
-        await page.wait(3);
         // Extract article content
         const data = await page.evaluate(`
       (() => {

package/dist/clis/zhihu/question.js

@@ -6,7 +6,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/dist/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/dist/commanderAdapter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { type CliCommand } from './registry.js';
+/**
+ * Register a single CliCommand as a Commander subcommand.
+ */
+export declare function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void;
+/**
+ * Register all commands from the registry onto a Commander program.
+ */
+export declare function registerAllCommands(program: Command, siteGroups: Map<string, Command>): void;

package/dist/commanderAdapter.js

@@ -0,0 +1,111 @@
+/**
+ * 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 chalk from 'chalk';
+import { 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, cmd) {
+    if (siteCmd.commands.some((c) => c.name() === cmd.name))
+        return;
+    const subCmd = siteCmd.command(cmd.name).description(cmd.description);
+    // Register positional args first, then named options
+    const positionalArgs = [];
+    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) => {
+        const actionOpts = actionArgs[positionalArgs.length] ?? {};
+        const startTime = Date.now();
+        // ── Collect kwargs ──────────────────────────────────────────────────
+        const kwargs = {};
+        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) => 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) {
+            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, siteGroups) {
+    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/dist/{engine.d.ts → discovery.d.ts}

@@ -7,14 +7,8 @@
  *    TS modules are loaded lazily only when their command is executed.
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
-import { type CliCommand } from './registry.js';
-import type { IPage } from './types.js';
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
  */
 export declare function discoverClis(...dirs: string[]): Promise<void>;
-/**
- * Execute a CLI command. Handles lazy-loading of TS modules.
- */
-export declare function executeCommand(cmd: CliCommand, page: IPage | null, rawKwargs: Record<string, any>, debug?: boolean): Promise<any>;

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

@@ -11,11 +11,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 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();
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
@@ -142,6 +138,7 @@ async function registerYamlCli(filePath, defaultSite) {
                     type: argDef?.type ?? 'str',
                     default: argDef?.default,
                     required: argDef?.required ?? false,
+                    positional: argDef?.positional ?? false,
                     help: argDef?.description ?? argDef?.help ?? '',
                     choices: argDef?.choices,
                 });
@@ -166,97 +163,3 @@ async function registerYamlCli(filePath, defaultSite) {
         log.warn(`Failed to load ${filePath}: ${err.message}`);
     }
 }
-/**
- * Validates and coerces arguments based on the command's Arg definitions.
- */
-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;
-        }
-    }
-    return result;
-}
-/**
- * Execute a CLI command. Handles lazy-loading of TS modules.
- */
-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.');
-            }
-        }
-        // 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/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,4 @@
 /**
- * Tests for engine.ts: CLI discovery and command execution.
+ * Tests for discovery and execution modules.
  */
 export {};

package/dist/engine.test.js

@@ -1,8 +1,9 @@
 /**
- * Tests for engine.ts: CLI discovery and command execution.
+ * Tests for discovery and execution modules.
  */
 import { describe, it, expect } from 'vitest';
-import { discoverClis, executeCommand } from './engine.js';
+import { discoverClis } from './discovery.js';
+import { executeCommand } from './execution.js';
 import { cli, Strategy } from './registry.js';
 describe('discoverClis', () => {
     it('handles non-existent directories gracefully', async () => {
@@ -23,7 +24,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 +38,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 +54,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 +63,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 +77,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,22 @@
+/**
+ * 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';
+/**
+ * Validates and coerces arguments based on the command's Arg definitions.
+ */
+export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any>): Record<string, any>;
+/**
+ * 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: Record<string, any>, debug?: boolean): Promise<any>;