@jackwener/opencli 1.7.17 → 1.7.19

package/dist/src/cli-argv-preprocess.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import { getBrowserSubcommandNames, rewriteBrowserArgv } from './cli-argv-preprocess.js';
+describe('rewriteBrowserArgv', () => {
+    it('rewrites `browser <session> <subcommand>` into `browser --session <name> <subcommand>`', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'state'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            'state',
+        ]);
+    });
+    it('rewrites with subcommand arguments preserved', () => {
+        expect(rewriteBrowserArgv(['browser', 'mercury', 'open', 'https://x.com'])).toEqual([
+            'browser',
+            '--session',
+            'mercury',
+            'open',
+            'https://x.com',
+        ]);
+    });
+    it('rewrites `browser <session> bind`', () => {
+        expect(rewriteBrowserArgv(['browser', 'mercury', 'bind'])).toEqual([
+            'browser',
+            '--session',
+            'mercury',
+            'bind',
+        ]);
+    });
+    it('leaves argv alone when session omitted and a subcommand follows', () => {
+        // Commander surfaces the required-flag error itself.
+        expect(rewriteBrowserArgv(['browser', 'state'])).toEqual(['browser', 'state']);
+        expect(rewriteBrowserArgv(['browser', 'bind'])).toEqual(['browser', 'bind']);
+    });
+    it('leaves argv alone when the token after `browser` is a flag', () => {
+        expect(rewriteBrowserArgv(['browser', '--help'])).toEqual(['browser', '--help']);
+        expect(rewriteBrowserArgv(['browser', '-h'])).toEqual(['browser', '-h']);
+    });
+    it('refuses the retired `opencli browser --session foo ...` user form', () => {
+        // The flag form is no longer a public entrance. Tests calling
+        // program.parseAsync directly bypass the preprocessor, so internal
+        // callers still work; but the user-facing pipeline throws.
+        expect(() => rewriteBrowserArgv(['browser', '--session', 'foo', 'state']))
+            .toThrowError(/no longer a public option/i);
+        expect(() => rewriteBrowserArgv(['browser', '--session=foo', 'state']))
+            .toThrowError(/no longer a public option/i);
+    });
+    it('leaves argv alone when `browser` is not present', () => {
+        expect(rewriteBrowserArgv(['twitter', 'tweets', '@elonmusk'])).toEqual([
+            'twitter',
+            'tweets',
+            '@elonmusk',
+        ]);
+        expect(rewriteBrowserArgv(['doctor'])).toEqual(['doctor']);
+    });
+    it('returns argv unchanged when `browser` is the last token', () => {
+        expect(rewriteBrowserArgv(['browser'])).toEqual(['browser']);
+    });
+    it('only rewrites when `browser` is the root command, not deeper in argv', () => {
+        // `opencli adapter init browser/x` — the literal `browser` is a path argument,
+        // not the root command. Must not be touched.
+        expect(rewriteBrowserArgv(['adapter', 'init', 'browser', 'x'])).toEqual([
+            'adapter',
+            'init',
+            'browser',
+            'x',
+        ]);
+        // Same for URLs or arbitrary arg values that happen to contain `browser`.
+        expect(rewriteBrowserArgv(['twitter', 'tweets', 'https://browser.example.com'])).toEqual([
+            'twitter',
+            'tweets',
+            'https://browser.example.com',
+        ]);
+        // First-match heuristic must NOT rewrite when an earlier non-flag token
+        // already established a different root command.
+        expect(rewriteBrowserArgv(['list', 'browser', 'state'])).toEqual([
+            'list',
+            'browser',
+            'state',
+        ]);
+    });
+    it('skips leading root flags before identifying the root command', () => {
+        // `--profile` takes a value — the value is not the command.
+        expect(rewriteBrowserArgv(['--profile', 'work', 'browser', 'mercury', 'state'])).toEqual([
+            '--profile',
+            'work',
+            'browser',
+            '--session',
+            'mercury',
+            'state',
+        ]);
+        // Long form with `=` separator consumes one slot only.
+        expect(rewriteBrowserArgv(['--profile=work', 'browser', 'mercury', 'state'])).toEqual([
+            '--profile=work',
+            'browser',
+            '--session',
+            'mercury',
+            'state',
+        ]);
+        // Boolean flags don't consume values.
+        expect(rewriteBrowserArgv(['-v', 'browser', 'mercury', 'state'])).toEqual([
+            '-v',
+            'browser',
+            '--session',
+            'mercury',
+            'state',
+        ]);
+    });
+    it('leaves argv alone when the root command is not `browser`, even if `browser` appears later', () => {
+        // The first browser keyword does NOT win — it must be at the root.
+        expect(rewriteBrowserArgv(['twitter', 'browser', 'work', 'state'])).toEqual([
+            'twitter',
+            'browser',
+            'work',
+            'state',
+        ]);
+    });
+    it('reserved subcommand list covers every known browser subcommand registered in cli.ts', () => {
+        const names = getBrowserSubcommandNames();
+        const required = [
+            'analyze', 'back', 'bind', 'check', 'click', 'close', 'console', 'dblclick',
+            'dialog', 'drag', 'eval', 'extract', 'fill', 'find', 'focus', 'frames',
+            'get', 'hover', 'init', 'keys', 'network', 'open', 'screenshot', 'scroll',
+            'select', 'state', 'tab', 'type', 'unbind', 'uncheck', 'upload', 'verify',
+            'wait',
+        ];
+        for (const name of required) {
+            expect(names.has(name)).toBe(true);
+        }
+    });
+});

package/dist/src/cli.js

@@ -8,8 +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, InvalidArgumentError } from 'commander';
-import { styleText } from 'node:util';
+import { Command, InvalidArgumentError, Option } from 'commander';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
 import { fullName, getRegistry, strategyLabel } from './registry.js';
 import { serializeCommand, formatArgSummary } from './serialization.js';
@@ -18,7 +17,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 { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, rootHelpData } from './help.js';
+import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, 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';
@@ -372,10 +371,13 @@ function getCommandOption(command, option) {
     return undefined;
 }
 function getBrowserSession(command) {
+    // The CLI surface is `opencli browser <session> <subcommand>`. main.ts rewrites
+    // argv to insert `--session <name>` before commander parses it; this helper
+    // reads back the rewritten flag.
     const raw = getCommandOption(command, 'session');
     if (typeof raw === 'string' && raw.trim())
         return raw.trim();
-    throw new Error('--session <name> is required for opencli browser commands');
+    throw new Error('<session> is a required positional argument: opencli browser <session> <command>');
 }
 function getBrowserContextId(command) {
     const raw = getCommandOption(command, 'profile');
@@ -523,31 +525,31 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             sites.set(cmd.site, g);
         }
         console.log();
-        console.log(styleText('bold', '  opencli') + styleText('dim', ' — available commands'));
+        console.log('  opencli' + ' — available commands');
         console.log();
         for (const [site, cmds] of sites) {
-            console.log(styleText(['bold', 'cyan'], `  ${site}`));
+            console.log(`  ${site}`);
             for (const cmd of cmds) {
                 const label = strategyLabel(cmd);
                 const tag = label === 'public'
-                    ? styleText('green', '[public]')
-                    : styleText('yellow', `[${label}]`);
-                const aliases = cmd.aliases?.length ? styleText('dim', ` (aliases: ${cmd.aliases.join(', ')})`) : '';
-                console.log(`    ${cmd.name} ${tag}${aliases}${cmd.description ? styleText('dim', ` — ${cmd.description}`) : ''}`);
+                    ? '[public]'
+                    : `[${label}]`;
+                const aliases = cmd.aliases?.length ? ` (aliases: ${cmd.aliases.join(', ')})` : '';
+                console.log(`    ${cmd.name} ${tag}${aliases}${cmd.description ? ` — ${cmd.description}` : ''}`);
             }
             console.log();
         }
         const externalClis = loadExternalClis();
         if (externalClis.length > 0) {
-            console.log(styleText(['bold', 'cyan'], '  external CLIs'));
+            console.log('  external CLIs');
             for (const ext of externalClis) {
                 const isInstalled = isBinaryInstalled(ext.binary);
-                const tag = isInstalled ? styleText('green', '[installed]') : styleText('yellow', '[auto-install]');
-                console.log(`    ${ext.name} ${tag}${ext.description ? styleText('dim', ` — ${ext.description}`) : ''}`);
+                const tag = isInstalled ? '[installed]' : '[auto-install]';
+                console.log(`    ${ext.name} ${tag}${ext.description ? ` — ${ext.description}` : ''}`);
             }
             console.log();
         }
-        console.log(styleText('dim', `  ${commands.length} built-in commands across ${sites.size} sites, ${externalClis.length} external CLIs`));
+        console.log(`  ${commands.length} built-in commands across ${sites.size} sites, ${externalClis.length} external CLIs`);
         console.log();
     });
     // ── Built-in: validate / verify ───────────────────────────────────────────
@@ -600,9 +602,23 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // All commands wrapped in browserAction() for consistent error handling.
     const browser = program
         .command('browser')
-        .option('--session <name>', 'Browser session to use')
+        // --session is an internal hidden option used by the daemon protocol and direct
+        // program.parseAsync callers (tests). User-facing surface is the <session>
+        // positional; main.ts argv preprocessor rewrites positional -> --session.
+        .addOption(new Option('--session <name>', 'Internal — set automatically from the <session> positional').hideHelp())
         .option('--window <mode>', 'Browser window mode: foreground or background')
-        .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+        .description('Browser control — navigate, click, type, extract, wait (no LLM needed)')
+        .usage('<session> <command> [options]')
+        .addHelpText('after', `
+<session> is a required positional: pass the name of the browser session every subcommand should operate on. Reuse the same name across calls to keep the tab/state alive; pick a different name to isolate parallel browser work.
+
+Examples:
+  $ opencli browser work open https://x.com
+  $ opencli browser work click 12
+  $ opencli browser work state
+  $ opencli browser work bind
+  $ opencli browser work unbind
+`);
     const originalBrowserDescription = browser.description();
     /**
      * Resolve a `<target>` (numeric ref or CSS selector) via the unified resolver.
@@ -723,8 +739,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         };
     }
     browser.command('bind')
-        .option('--session <name>', 'Browser session name to bind')
-        .description('Bind the current Chrome tab/window to a browser session')
+        .description('Bind the current Chrome tab/window to the browser session named by <session>')
         .action(async (optsOrCommand, maybeCommand) => {
         const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
         const session = getBrowserSession(command);
@@ -754,8 +769,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         }
     });
     browser.command('unbind')
-        .option('--session <name>', 'Browser session name to detach')
-        .description('Detach a bound browser session without closing the user tab/window')
+        .description('Detach the bound browser session named by <session> without closing the user tab/window')
         .action(async (optsOrCommand, maybeCommand) => {
         const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
         const session = getBrowserSession(command);
@@ -2579,18 +2593,18 @@ cli({
             await discoverPlugins();
             if (Array.isArray(result)) {
                 if (result.length === 0) {
-                    console.log(styleText('yellow', 'No plugins were installed (all skipped or incompatible).'));
+                    console.log('No plugins were installed (all skipped or incompatible).');
                 }
                 else {
-                    console.log(styleText('green', `\u2705 Installed ${result.length} plugin(s) from monorepo: ${result.join(', ')}`));
+                    console.log(`\u2705 Installed ${result.length} plugin(s) from monorepo: ${result.join(', ')}`);
                 }
             }
             else {
-                console.log(styleText('green', `\u2705 Plugin "${result}" installed successfully. Commands are ready to use.`));
+                console.log(`\u2705 Plugin "${result}" installed successfully. Commands are ready to use.`);
             }
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
@@ -2602,10 +2616,10 @@ cli({
         const { uninstallPlugin } = await import('./plugin.js');
         try {
             uninstallPlugin(name);
-            console.log(styleText('green', `✅ Plugin "${name}" uninstalled.`));
+            console.log(`✅ Plugin "${name}" uninstalled.`);
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
@@ -2616,12 +2630,12 @@ cli({
         .option('--all', 'Update all installed plugins')
         .action(async (name, opts) => {
         if (!name && !opts.all) {
-            console.error(styleText('red', 'Error: Please specify a plugin name or use the --all flag.'));
+            console.error('Error: Please specify a plugin name or use the --all flag.');
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         if (name && opts.all) {
-            console.error(styleText('red', 'Error: Cannot specify both a plugin name and --all.'));
+            console.error('Error: Cannot specify both a plugin name and --all.');
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
@@ -2633,36 +2647,36 @@ cli({
                 await discoverPlugins();
             }
             let hasErrors = false;
-            console.log(styleText('bold', '  Update Results:'));
+            console.log('  Update Results:');
             for (const result of results) {
                 if (result.success) {
-                    console.log(`  ${styleText('green', '✓')} ${result.name}`);
+                    console.log(`  ✓ ${result.name}`);
                     continue;
                 }
                 hasErrors = true;
-                console.log(`  ${styleText('red', '✗')} ${result.name} — ${styleText('dim', String(result.error))}`);
+                console.log(`  ✗ ${result.name} — ${String(result.error)}`);
             }
             if (results.length === 0) {
-                console.log(styleText('dim', '  No plugins installed.'));
+                console.log('  No plugins installed.');
                 return;
             }
             console.log();
             if (hasErrors) {
-                console.error(styleText('red', 'Completed with some errors.'));
+                console.error('Completed with some errors.');
                 process.exitCode = EXIT_CODES.GENERIC_ERROR;
             }
             else {
-                console.log(styleText('green', '✅ All plugins updated successfully.'));
+                console.log('✅ All plugins updated successfully.');
             }
             return;
         }
         try {
             updatePlugin(name);
             await discoverPlugins();
-            console.log(styleText('green', `✅ Plugin "${name}" updated successfully.`));
+            console.log(`✅ Plugin "${name}" updated successfully.`);
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
@@ -2674,8 +2688,8 @@ cli({
         const { listPlugins } = await import('./plugin.js');
         const plugins = listPlugins();
         if (plugins.length === 0) {
-            console.log(styleText('dim', '  No plugins installed.'));
-            console.log(styleText('dim', '  Install one with: opencli plugin install github:user/repo'));
+            console.log('  No plugins installed.');
+            console.log('  Install one with: opencli plugin install github:user/repo');
             return;
         }
         if (opts.format === 'json') {
@@ -2688,7 +2702,7 @@ cli({
             return;
         }
         console.log();
-        console.log(styleText('bold', '  Installed plugins'));
+        console.log('  Installed plugins');
         console.log();
         // Group by monorepo
         const standalone = plugins.filter((p) => !p.monorepoName);
@@ -2701,24 +2715,24 @@ cli({
             monoGroups.set(p.monorepoName, g);
         }
         for (const p of standalone) {
-            const version = p.version ? styleText('green', ` @${p.version}`) : '';
-            const desc = p.description ? styleText('dim', ` — ${p.description}`) : '';
-            const cmds = p.commands.length > 0 ? styleText('dim', ` (${p.commands.join(', ')})`) : '';
-            const src = p.source ? styleText('dim', ` ← ${p.source}`) : '';
-            console.log(`  ${styleText('cyan', p.name)}${version}${desc}${cmds}${src}`);
+            const version = p.version ? ` @${p.version}` : '';
+            const desc = p.description ? ` — ${p.description}` : '';
+            const cmds = p.commands.length > 0 ? ` (${p.commands.join(', ')})` : '';
+            const src = p.source ? ` ← ${p.source}` : '';
+            console.log(`  ${p.name}${version}${desc}${cmds}${src}`);
         }
         for (const [mono, group] of monoGroups) {
             console.log();
-            console.log(styleText(['bold', 'magenta'], `  📦 ${mono}`) + styleText('dim', ' (monorepo)'));
+            console.log(`  📦 ${mono}` + ' (monorepo)');
             for (const p of group) {
-                const version = p.version ? styleText('green', ` @${p.version}`) : '';
-                const desc = p.description ? styleText('dim', ` — ${p.description}`) : '';
-                const cmds = p.commands.length > 0 ? styleText('dim', ` (${p.commands.join(', ')})`) : '';
-                console.log(`    ${styleText('cyan', p.name)}${version}${desc}${cmds}`);
+                const version = p.version ? ` @${p.version}` : '';
+                const desc = p.description ? ` — ${p.description}` : '';
+                const cmds = p.commands.length > 0 ? ` (${p.commands.join(', ')})` : '';
+                console.log(`    ${p.name}${version}${desc}${cmds}`);
             }
         }
         console.log();
-        console.log(styleText('dim', `  ${plugins.length} plugin(s) installed`));
+        console.log(`  ${plugins.length} plugin(s) installed`);
         console.log();
     });
     pluginCmd
@@ -2734,20 +2748,20 @@ cli({
                 dir: opts.dir,
                 description: opts.description,
             });
-            console.log(styleText('green', `✅ Plugin scaffold created at ${result.dir}`));
+            console.log(`✅ Plugin scaffold created at ${result.dir}`);
             console.log();
-            console.log(styleText('bold', '  Files created:'));
+            console.log('  Files created:');
             for (const f of result.files) {
-                console.log(`    ${styleText('cyan', f)}`);
+                console.log(`    ${f}`);
             }
             console.log();
-            console.log(styleText('dim', '  Next steps:'));
-            console.log(styleText('dim', `    cd ${result.dir}`));
-            console.log(styleText('dim', `    opencli plugin install file://${result.dir}`));
-            console.log(styleText('dim', `    opencli ${name} hello`));
+            console.log('  Next steps:');
+            console.log(`    cd ${result.dir}`);
+            console.log(`    opencli plugin install file://${result.dir}`);
+            console.log(`    opencli ${name} hello`);
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
@@ -2800,21 +2814,21 @@ cli({
             await fs.promises.access(builtinSiteDir);
         }
         catch {
-            console.error(styleText('red', `Error: Site "${site}" not found in official adapters.`));
+            console.error(`Error: Site "${site}" not found in official adapters.`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         try {
             await fs.promises.access(userSiteDir);
-            console.error(styleText('yellow', `Site "${site}" already exists in ~/.opencli/clis/. Use "opencli adapter reset ${site}" first to restore official version.`));
+            console.error(`Site "${site}" already exists in ~/.opencli/clis/. Use "opencli adapter reset ${site}" first to restore official version.`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         catch { /* good, doesn't exist yet */ }
         fs.cpSync(builtinSiteDir, userSiteDir, { recursive: true });
-        console.log(styleText('green', `✅ Ejected "${site}" to ~/.opencli/clis/${site}/`));
+        console.log(`✅ Ejected "${site}" to ~/.opencli/clis/${site}/`);
         console.log('You can now edit the adapter files. Changes take effect immediately.');
-        console.log(styleText('yellow', 'Note: Official updates to this adapter will overwrite your changes.'));
+        console.log('Note: Official updates to this adapter will overwrite your changes.');
     });
     adapterCmd
         .command('reset')
@@ -2835,7 +2849,7 @@ cli({
                 for (const dir of dirs) {
                     fs.rmSync(path.join(userClisDir, dir.name), { recursive: true, force: true });
                 }
-                console.log(styleText('green', `✅ Reset ${dirs.length} site(s). All adapters now use official baseline.`));
+                console.log(`✅ Reset ${dirs.length} site(s). All adapters now use official baseline.`);
             }
             catch {
                 console.log('No local sites to reset.');
@@ -2843,7 +2857,7 @@ cli({
             return;
         }
         if (!site) {
-            console.error(styleText('red', 'Error: Please specify a site name or use --all.'));
+            console.error('Error: Please specify a site name or use --all.');
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
@@ -2852,14 +2866,14 @@ cli({
             await fs.promises.access(userSiteDir);
         }
         catch {
-            console.error(styleText('yellow', `Site "${site}" has no local override.`));
+            console.error(`Site "${site}" has no local override.`);
             return;
         }
         const isOfficial = fs.existsSync(path.join(BUILTIN_CLIS, site));
         fs.rmSync(userSiteDir, { recursive: true, force: true });
-        console.log(styleText('green', isOfficial
+        console.log(isOfficial
             ? `✅ Reset "${site}". Now using official baseline.`
-            : `✅ Removed custom site "${site}".`));
+            : `✅ Removed custom site "${site}".`);
     });
     // ── Built-in: browser profile selection ──────────────────────────────────
     const profileCmd = program.command('profile').description('Manage Browser Bridge Chrome profiles');
@@ -2873,26 +2887,26 @@ cli({
         const config = loadProfileConfig();
         const profiles = status?.profiles ?? [];
         if (!status) {
-            console.log(styleText('yellow', 'Daemon is not running. Run opencli doctor after opening Chrome.'));
+            console.log('Daemon is not running. Run opencli doctor after opening Chrome.');
             return;
         }
         if (isDaemonStale(status, PKG_VERSION) || !Array.isArray(status.profiles)) {
-            console.log(styleText('yellow', `Daemon ${formatDaemonVersion(status)} is stale for CLI v${PKG_VERSION}.`));
-            console.log(styleText('dim', 'Run: opencli daemon restart'));
+            console.log(`Daemon ${formatDaemonVersion(status)} is stale for CLI v${PKG_VERSION}.`);
+            console.log('Run: opencli daemon restart');
             return;
         }
         if (profiles.length === 0) {
-            console.log(styleText('yellow', 'No Browser Bridge profiles connected.'));
-            console.log(styleText('dim', 'Open a Chrome profile with the OpenCLI extension installed, then run opencli profile list again.'));
+            console.log('No Browser Bridge profiles connected.');
+            console.log('Open a Chrome profile with the OpenCLI extension installed, then run opencli profile list again.');
             return;
         }
         const knownContextIds = new Set(profiles.map((profile) => profile.contextId));
-        console.log(styleText('bold', 'Connected Browser Bridge profiles'));
+        console.log('Connected Browser Bridge profiles');
         console.log();
         for (const profile of profiles) {
             const alias = aliasForContextId(config, profile.contextId);
-            const defaultMark = config.defaultContextId === profile.contextId ? styleText('green', ' default') : '';
-            const aliasText = alias ? ` ${styleText('cyan', alias)}` : '';
+            const defaultMark = config.defaultContextId === profile.contextId ? ' default' : '';
+            const aliasText = alias ? ` ${alias}` : '';
             const version = profile.extensionVersion ? ` v${profile.extensionVersion}` : ' version unknown';
             console.log(`  ${profile.contextId}${aliasText}${defaultMark} — connected${version}`);
         }
@@ -2900,14 +2914,14 @@ cli({
             .filter(([, contextId]) => !knownContextIds.has(contextId));
         if (disconnectedAliases.length > 0 || (config.defaultContextId && !knownContextIds.has(config.defaultContextId))) {
             console.log();
-            console.log(styleText('dim', 'Disconnected saved profiles:'));
+            console.log('Disconnected saved profiles:');
             const shown = new Set();
             for (const [alias, contextId] of disconnectedAliases) {
                 shown.add(contextId);
-                console.log(styleText('dim', `  ${contextId} ${alias} — not connected`));
+                console.log(`  ${contextId} ${alias} — not connected`);
             }
             if (config.defaultContextId && !shown.has(config.defaultContextId) && !knownContextIds.has(config.defaultContextId)) {
-                console.log(styleText('dim', `  ${config.defaultContextId} — default, not connected`));
+                console.log(`  ${config.defaultContextId} — default, not connected`);
             }
         }
     });
@@ -2919,10 +2933,10 @@ cli({
         .action((contextId, alias) => {
         try {
             renameProfile(contextId, alias);
-            console.log(`Profile ${contextId} is now aliased as ${styleText('cyan', alias)}.`);
+            console.log(`Profile ${contextId} is now aliased as ${alias}.`);
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
         }
     });
@@ -2933,10 +2947,10 @@ cli({
         .action((profile) => {
         try {
             const config = setDefaultProfile(profile);
-            console.log(`Default Browser Bridge profile: ${styleText('cyan', config.defaultContextId ?? profile)}`);
+            console.log(`Default Browser Bridge profile: ${config.defaultContextId ?? profile}`);
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
         }
     });
@@ -2968,7 +2982,7 @@ cli({
         .action((name) => {
         const ext = externalClis.find(e => e.name === name);
         if (!ext) {
-            console.error(styleText('red', `External CLI '${name}' not found in registry.`));
+            console.error(`External CLI '${name}' not found in registry.`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
@@ -3013,7 +3027,7 @@ cli({
             executeExternalCli(name, args, externalClis);
         }
         catch (err) {
-            console.error(styleText('red', `Error: ${getErrorMessage(err)}`));
+            console.error(`Error: ${getErrorMessage(err)}`);
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     }
@@ -3076,15 +3090,38 @@ cli({
     program.configureHelp({
         visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
     });
+    // When an ancestor command declares a leading positional via `.usage(...)`
+    // (e.g. `browser` -> `<session> <command> [options]`), inject the positional
+    // between that ancestor's name and the next path segment so the help Usage
+    // line is accurate: `Usage: opencli browser <session> click [target] [options]`
+    // instead of `opencli browser click [target] [options]`. Commander does NOT
+    // inherit configureHelp into subcommands, so we walk the descendant tree and
+    // apply the override on each.
+    const ancestorAwareCommandUsage = (cmd) => {
+        const ancestors = [];
+        let ancestor = cmd.parent;
+        while (ancestor) {
+            const positional = leadingPositionalFromUsage(ancestor);
+            ancestors.unshift(positional ? `${ancestor.name()} ${positional}` : ancestor.name());
+            ancestor = ancestor.parent;
+        }
+        return [...ancestors, cmd.name(), cmd.usage()].filter(Boolean).join(' ').trim();
+    };
+    function applyAncestorAwareUsage(cmd) {
+        cmd.configureHelp({ commandUsage: ancestorAwareCommandUsage });
+        for (const sub of cmd.commands)
+            applyAncestorAwareUsage(sub);
+    }
+    applyAncestorAwareUsage(browser);
     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.
     program.on('command:*', (operands) => {
         const binary = operands[0];
-        console.error(styleText('red', `error: unknown command '${binary}'`));
+        console.error(`error: unknown command '${binary}'`);
         if (isBinaryInstalled(binary)) {
-            console.error(styleText('dim', `  Tip: '${binary}' exists on your PATH. Use 'opencli external register ${binary}' to add it as an external CLI.`));
+            console.error(`  Tip: '${binary}' exists on your PATH. Use 'opencli external register ${binary}' to add it as an external CLI.`);
         }
         program.outputHelp();
         process.exitCode = EXIT_CODES.USAGE_ERROR;