@jackwener/opencli 1.7.12 → 1.7.14

package/dist/src/cli.js

@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { styleText } from 'node:util';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
 import { fullName, getRegistry, strategyLabel } from './registry.js';
@@ -18,7 +18,7 @@ import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { formatRootAdapterHelpText, installStructuredHelp, rootHelpData } from './help.js';
+import { classifyAdapter, formatRootAdapterHelpText, installStructuredHelp, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
@@ -316,7 +316,9 @@ async function resolveStoredBrowserTarget(page, scope = DEFAULT_BROWSER_WORKSPAC
 async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE, contextId) {
     const { BrowserBridge } = await import('./browser/index.js');
     const bridge = new BrowserBridge();
-    const envTimeout = process.env.OPENCLI_BROWSER_TIMEOUT;
+    // Idle timeout: how long the browser workspace lease stays alive between commands
+    // (controls when the automation tab is released). Not the per-command runtime timeout.
+    const envTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;
     const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;
     const page = await bridge.connect({
         timeout: 30,
@@ -389,6 +391,16 @@ function parsePositiveIntOption(val, label, fallback) {
     }
     return parsed;
 }
+function parseScreenshotDim(val, label) {
+    if (!/^\d+$/.test(val)) {
+        throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
+    }
+    const parsed = parseInt(val, 10);
+    if (parsed <= 0) {
+        throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
+    }
+    return parsed;
+}
 function applyVerbose(opts) {
     if (opts.verbose)
         process.env.OPENCLI_VERBOSE = '1';
@@ -888,14 +900,22 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(JSON.stringify(frames, null, 2));
     }));
     addBrowserTabOption(browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)'))
+        .option('--full-page', 'Capture the full scrollable page, not just the viewport', false)
+        .option('--width <n>', 'Override viewport width in CSS pixels for this screenshot only', (v) => parseScreenshotDim(v, 'width'))
+        .option('--height <n>', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)', (v) => parseScreenshotDim(v, 'height'))
         .description('Take screenshot')
-        .action(browserAction(async (page, path) => {
+        .action(browserAction(async (page, path, opts) => {
+        const shotOpts = {
+            fullPage: opts.fullPage === true,
+            width: opts.width,
+            height: opts.height,
+        };
         if (path) {
-            await page.screenshot({ path });
+            await page.screenshot({ ...shotOpts, path });
             console.log(`Screenshot saved to: ${path}`);
         }
         else {
-            console.log(await page.screenshot({ format: 'png' }));
+            console.log(await page.screenshot({ ...shotOpts, format: 'png' }));
         }
     }));
     addBrowserTabOption(browser.command('console'))
@@ -1313,6 +1333,33 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             autocomplete: !!isAutocomplete,
         }, null, 2));
     }));
+    addBrowserTabOption(browser.command('fill')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .argument('<text>', 'Text to set exactly')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Set input/textarea/contenteditable text exactly and verify the value — JSON envelope {filled, verified, text, actual}'))
+        .action(browserAction(async (page, target, text, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.fillText(String(target), String(text), parsed.opts);
+        if (!result.verified)
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        console.log(JSON.stringify({
+            filled: result.filled,
+            verified: result.verified,
+            target: String(target),
+            text: String(text),
+            actual: result.actual,
+            length: result.length,
+            matches_n: result.matches_n,
+            match_level: result.match_level,
+            ...(result.mode ? { mode: result.mode } : {}),
+        }, null, 2));
+    }));
     addBrowserTabOption(browser.command('select')
         .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector of a <select> element')
         .argument('<option>', 'Option text (or value) to select')
@@ -2036,10 +2083,10 @@ cli({
         }
     });
     // ── Session ──
-    browser.command('close').description('Close the automation window')
+    browser.command('close').description('Release the current automation tab lease')
         .action(browserAction(async (page) => {
         await page.closeWindow?.();
-        console.log('Automation window closed');
+        console.log('Automation tab lease released');
     }));
     // ── Built-in: doctor / completion ──────────────────────────────────────────
     program
@@ -2539,11 +2586,29 @@ cli({
     siteGroups.set('antigravity', antigravityCmd);
     const siteNames = registerAllCommands(program, siteGroups);
     applyRootSubcommandSummaries(program);
-    const siteNameSet = new Set(siteNames);
+    // ── Help-text grouping: External CLIs / App adapters / Site adapters ──
+    // Classification derives from each adapter's `domain` field — see classifyAdapter.
+    // External CLIs are taken from the externalClis registry (passthrough binaries).
+    const externalNames = externalClis.map(ext => ext.name);
+    const siteDomains = new Map();
+    for (const [, cmd] of getRegistry()) {
+        if (!siteDomains.has(cmd.site))
+            siteDomains.set(cmd.site, cmd.domain);
+    }
+    const apps = [];
+    const sites = [];
+    for (const site of siteNames) {
+        if (classifyAdapter(siteDomains.get(site)) === 'app')
+            apps.push(site);
+        else
+            sites.push(site);
+    }
+    const adapterGroups = { external: externalNames, apps, sites };
+    const adapterNameSet = new Set([...externalNames, ...siteNames]);
     program.configureHelp({
-        visibleCommands: (command) => command.commands.filter(child => command !== program || !siteNameSet.has(child.name())),
+        visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
     });
-    installStructuredHelp(program, () => rootHelpData(program, siteNames), () => formatRootAdapterHelpText(siteNames));
+    installStructuredHelp(program, () => rootHelpData(program, adapterGroups), () => formatRootAdapterHelpText(adapterGroups));
     // ── Unknown command fallback ──────────────────────────────────────────────
     // Security: do NOT auto-discover and register arbitrary system binaries.
     // Only explicitly registered external CLIs are allowed.

package/dist/src/cli.test.js

@@ -96,6 +96,90 @@ describe('createProgram root help descriptions', () => {
                 registry.set(key, value);
         }
     });
+    it('groups adapters into App / Site buckets by domain field', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+            });
+            cli({
+                site: 'chatwise',
+                name: 'ask',
+                access: 'write',
+                description: 'Ask Chatwise desktop app',
+                domain: 'localhost',
+                strategy: Strategy.UI,
+                browser: true,
+            });
+            const program = createProgram('', '');
+            const help = program.helpInformation();
+            // Two separate sections, each with own count
+            expect(help).toContain('App adapters (1):');
+            expect(help).toMatch(/App adapters \(1\):\n {2}chatwise/);
+            expect(help).toContain('Site adapters (1):');
+            expect(help).toMatch(/Site adapters \(1\):\n {2}bilibili/);
+            // App adapters appear before Site adapters (External CLIs are absent here)
+            expect(help.indexOf('App adapters')).toBeLessThan(help.indexOf('Site adapters'));
+        }
+        finally {
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('exposes external_clis / app_adapters / site_adapters in structured help', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        const argv = process.argv;
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+            });
+            cli({
+                site: 'chatwise',
+                name: 'ask',
+                access: 'write',
+                description: 'Ask Chatwise desktop app',
+                domain: 'localhost',
+                strategy: Strategy.UI,
+                browser: true,
+            });
+            const program = createProgram('', '');
+            process.argv = ['node', 'opencli', '--help', '-f', 'yaml'];
+            const data = yaml.load(program.helpInformation());
+            expect(data.app_adapters.count).toBe(1);
+            expect(data.app_adapters.apps).toEqual(['chatwise']);
+            expect(data.site_adapters.count).toBe(1);
+            expect(data.site_adapters.sites).toEqual(['bilibili']);
+            expect(data.external_clis.count).toBeGreaterThanOrEqual(0);
+            expect(Array.isArray(data.external_clis.clis)).toBe(true);
+            // Adapters must NOT leak into the core commands list
+            const commandNames = data.commands.map((cmd) => cmd.name);
+            expect(commandNames).not.toContain('bilibili');
+            expect(commandNames).not.toContain('chatwise');
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
     it('renders root structured help with built-ins and site adapter names', () => {
         const registry = getRegistry();
         const snapshot = new Map(registry);
@@ -139,6 +223,7 @@ describe('createProgram root help descriptions', () => {
                 strategy: Strategy.PUBLIC,
                 browser: false,
                 args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+                columns: ['title', 'url'],
             });
             const program = createProgram('', '');
             const site = program.commands.find(cmd => cmd.name() === 'bilibili');
@@ -151,10 +236,99 @@ describe('createProgram root help descriptions', () => {
                     name: 'hot',
                     access: 'read',
                     description: 'Bilibili hot videos',
+                    browser: false,
                     example: 'opencli bilibili hot -f yaml',
-                    args: [{ name: 'limit', type: 'int', default: 20 }],
+                    command_options: [{ name: 'limit', type: 'int', default: 20 }],
+                    columns: ['title', 'url'],
                 },
             ]);
+            expect(data.commands[0]).not.toHaveProperty('args');
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('renders per-site text help without per-command common option noise', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+            });
+            cli({
+                site: 'bilibili',
+                name: 'video',
+                access: 'read',
+                description: 'Read one video',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: true,
+                args: [{ name: 'bvid', positional: true, required: true, help: 'Video id' }],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            expect(site).toBeTruthy();
+            const help = site.helpInformation();
+            expect(help).toContain('hot [options]  [read] Bilibili hot videos');
+            expect(help).toContain('video <bvid>   [read] Read one video');
+            expect(help).toContain('hot [options]');
+            expect(help).not.toContain('video <bvid> [options]');
+            expect(help).not.toContain('\nOptions:');
+            expect(help).toContain('Common options:');
+            expect(help).toContain('-f, --format <fmt>');
+            expect(help).toContain('--trace <mode>');
+            expect(help).toContain('get all command args/options in one structured response');
+        }
+        finally {
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('separates command args from common options in structured help', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        const argv = process.argv;
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'video',
+                access: 'read',
+                description: 'Read one video',
+                strategy: Strategy.PUBLIC,
+                domain: 'www.bilibili.com',
+                browser: true,
+                args: [
+                    { name: 'bvid', positional: true, required: true, help: 'Video id' },
+                    { name: 'with-comments', type: 'boolean', default: false, help: 'Include comments' },
+                ],
+                columns: ['title', 'url'],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            const command = site.commands.find(cmd => cmd.name() === 'video');
+            expect(command).toBeTruthy();
+            process.argv = ['node', 'opencli', 'bilibili', 'video', '--help', '-f', 'yaml'];
+            const data = yaml.load(command.helpInformation());
+            expect(data.usage).toBe('opencli bilibili video <bvid> [options]');
+            expect(data.browser).toBe(true);
+            expect(data.domain).toBe('www.bilibili.com');
+            expect(data.positionals).toMatchObject([{ name: 'bvid', positional: true, required: true }]);
+            expect(data.command_options).toMatchObject([{ name: 'with-comments', default: false }]);
+            expect(data.common_options.map((option) => option.name)).toEqual(['format', 'trace', 'verbose', 'help']);
+            expect(data.columns).toEqual(['title', 'url']);
+            expect(data).not.toHaveProperty('args');
         }
         finally {
             process.argv = argv;
@@ -1624,6 +1798,16 @@ describe('browser click/type commands', () => {
         evaluate: vi.fn().mockResolvedValue(false),
         click: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
         typeText: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        fillText: vi.fn().mockResolvedValue({
+            filled: true,
+            verified: true,
+            expected: '',
+            actual: '',
+            length: 0,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'input',
+        }),
         wait: vi.fn().mockResolvedValue(undefined),
     }));
     it('emits {clicked, target, matches_n, match_level} on success', async () => {
@@ -1721,6 +1905,62 @@ describe('browser click/type commands', () => {
         expect(browserState.page.click).toHaveBeenCalledWith('.field', { nth: 3 });
         expect(browserState.page.typeText).toHaveBeenCalledWith('.field', 'x', { nth: 3 });
     });
+    it('fill: delegates exact raw text to page.fillText and emits verification details', async () => {
+        browserState.page.fillText.mockResolvedValueOnce({
+            filled: true,
+            verified: true,
+            expected: 'line1\\n/ / raw',
+            actual: 'line1\\n/ / raw',
+            length: 14,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'textarea',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '#msg', 'line1\\n/ / raw']);
+        expect(browserState.page.fillText).toHaveBeenCalledWith('#msg', 'line1\\n/ / raw', {});
+        expect(lastJsonLog()).toEqual({
+            filled: true,
+            verified: true,
+            target: '#msg',
+            text: 'line1\\n/ / raw',
+            actual: 'line1\\n/ / raw',
+            length: 14,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'textarea',
+        });
+        expect(process.exitCode).toBeUndefined();
+    });
+    it('fill: sets a non-zero exit code when verification fails', async () => {
+        browserState.page.fillText.mockResolvedValueOnce({
+            filled: true,
+            verified: false,
+            expected: 'expected',
+            actual: 'actual',
+            length: 6,
+            matches_n: 1,
+            match_level: 'exact',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '#msg', 'expected']);
+        expect(lastJsonLog()).toEqual({
+            filled: true,
+            verified: false,
+            target: '#msg',
+            text: 'expected',
+            actual: 'actual',
+            length: 6,
+            matches_n: 1,
+            match_level: 'exact',
+        });
+        expect(process.exitCode).toBeDefined();
+    });
+    it('fill: forwards --nth to page.fillText', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '.field', 'x', '--nth', '2']);
+        expect(browserState.page.fillText).toHaveBeenCalledWith('.field', 'x', { nth: 2 });
+    });
 });
 describe('browser select command', () => {
     const { lastJsonLog } = installSelectorFirstTestHarness('select', () => ({

package/dist/src/commanderAdapter.js

@@ -12,10 +12,9 @@
 import { log } from './logger.js';
 import yaml from 'js-yaml';
 import { fullName, getRegistry } from './registry.js';
-import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand, prepareCommandArgs } from './execution.js';
-import { commandHelpData, formatSiteCommandDescription, installStructuredHelp, siteHelpData, } from './help.js';
+import { commandHelpData, formatCommandHelpText, formatCommandListTerm, formatSiteCommandDescription, formatSiteHelpText, getRequestedHelpFormat, renderStructuredHelp, siteHelpData, } from './help.js';
 import { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
 /**
  * Register a single CliCommand as a Commander subcommand.
@@ -49,7 +48,16 @@ export function registerCommandToProgram(siteCmd, cmd) {
         .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
         .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
         .option('-v, --verbose', 'Debug output', false);
-    installStructuredHelp(subCmd, () => commandHelpData(cmd), () => formatRegistryHelpText(cmd));
+    const originalHelpInformation = subCmd.helpInformation.bind(subCmd);
+    subCmd.helpInformation = ((contextOptions) => {
+        const format = getRequestedHelpFormat();
+        if (format)
+            return renderStructuredHelp(commandHelpData(cmd), format);
+        // Keep a fallback reference so future Commander upgrades still initialize
+        // internal help state before we render the cleaner grouped command help.
+        void originalHelpInformation(contextOptions);
+        return formatCommandHelpText(cmd);
+    });
     subCmd.action(async (...actionArgs) => {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
         const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
@@ -89,11 +97,6 @@ export function registerCommandToProgram(siteCmd, cmd) {
             const formatExplicit = subCmd.getOptionValueSource('format') === 'cli';
             if (verbose)
                 process.env.OPENCLI_VERBOSE = '1';
-            if (cmd.deprecated) {
-                const message = typeof cmd.deprecated === 'string' ? cmd.deprecated : `${fullName(cmd)} is deprecated.`;
-                const replacement = cmd.replacedBy ? ` Use ${cmd.replacedBy} instead.` : '';
-                log.warn(`Deprecated: ${message}${replacement}`);
-            }
             const globals = typeof subCmd.optsWithGlobals === 'function' ? subCmd.optsWithGlobals() : {};
             const result = await executeCommand(cmd, kwargs, verbose, {
                 prepared: true,
@@ -179,7 +182,18 @@ export function registerAllCommands(program, siteGroups) {
         for (const cmd of commands) {
             registerCommandToProgram(siteCmd, cmd);
         }
-        installStructuredHelp(siteCmd, () => siteHelpData(site, commands));
+        const commandTerms = new Map(commands.map(cmd => [cmd.name, formatCommandListTerm(cmd)]));
+        siteCmd.configureHelp({
+            subcommandTerm: command => commandTerms.get(command.name()) ?? command.name(),
+        });
+        const originalSiteHelpInformation = siteCmd.helpInformation.bind(siteCmd);
+        siteCmd.helpInformation = ((contextOptions) => {
+            const format = getRequestedHelpFormat();
+            if (format)
+                return renderStructuredHelp(siteHelpData(site, commands), format);
+            void originalSiteHelpInformation(contextOptions);
+            return formatSiteHelpText(site, commands);
+        });
     }
     return [...commandsBySite.keys()].sort((a, b) => a.localeCompare(b));
 }

package/dist/src/commanderAdapter.test.js

@@ -279,7 +279,6 @@ describe('commanderAdapter error envelope output', () => {
         expect(output).toContain('xsec_token');
         expect(output).toContain('--trace=retain-on-failure');
         expect(output).toContain('opencli xiaohongshu note --trace retain-on-failure');
-        expect(output).not.toContain('OPENCLI_DIAGNOSTIC');
         stderrSpy.mockRestore();
     });
     it('outputs YAML error envelope for selector errors', async () => {

package/dist/src/discovery.js

@@ -131,12 +131,11 @@ async function loadFromManifest(manifestPath, clisDir) {
                 browser: entry.browser,
                 args: entry.args ?? [],
                 columns: entry.columns,
+                defaultFormat: entry.defaultFormat,
                 pipeline: entry.pipeline,
-                timeoutSeconds: entry.timeout,
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
-                deprecated: entry.deprecated,
-                replacedBy: entry.replacedBy,
                 navigateBefore: entry.navigateBefore,
+                browserSession: entry.browserSession,
                 _lazy: true,
                 _modulePath: modulePath,
             };
@@ -170,7 +169,6 @@ async function discoverClisFromFs(dir) {
         await Promise.all(files.map(async (file) => {
             const filePath = path.join(siteDir, file);
             if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-                log.warn(`Ignoring YAML adapter ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
                 return;
             }
             if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
@@ -218,7 +216,6 @@ async function discoverPluginDir(dir, site) {
     await Promise.all(files.map(async (file) => {
         const filePath = path.join(dir, file);
         if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-            log.warn(`Ignoring YAML plugin ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
             return;
         }
         if (file.endsWith('.js') && !file.endsWith('.d.js')) {

package/dist/src/errors.js

@@ -73,7 +73,7 @@ export class AuthRequiredError extends CliError {
 }
 export class TimeoutError extends CliError {
     constructor(label, seconds, hint) {
-        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var', EXIT_CODES.TEMPFAIL);
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with --timeout <seconds> (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)', EXIT_CODES.TEMPFAIL);
     }
 }
 export class ArgumentError extends CliError {

package/dist/src/execution.d.ts

@@ -4,7 +4,7 @@
  * 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
+ * 3. Domain pre-navigation for cookie strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)