@jackwener/opencli 1.7.10 → 1.7.12

package/dist/src/cli.js

@@ -18,6 +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 { 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';
@@ -392,6 +393,20 @@ function applyVerbose(opts) {
     if (opts.verbose)
         process.env.OPENCLI_VERBOSE = '1';
 }
+function formatChildCommandSummary(command) {
+    return [...new Set(command.commands.map(child => child.name()))]
+        .sort((a, b) => a.localeCompare(b))
+        .join(', ');
+}
+function applyRootSubcommandSummaries(program) {
+    for (const command of program.commands) {
+        if (command.commands.length === 0)
+            continue;
+        const summary = formatChildCommandSummary(command);
+        if (summary)
+            command.description(summary);
+    }
+}
 export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     const program = new Command();
     // enablePositionalOptions: prevents parent from consuming flags meant for subcommands;
@@ -421,13 +436,14 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                     name: c.name,
                     aliases: c.aliases?.join(', ') ?? '',
                     description: c.description,
+                    access: c.access,
                     strategy: strategyLabel(c),
                     browser: !!c.browser,
                     args: formatArgSummary(c.args),
                 }));
             renderOutput(rows, {
                 fmt,
-                columns: ['command', 'site', 'name', 'aliases', 'description', 'strategy', 'browser', 'args',
+                columns: ['command', 'site', 'name', 'aliases', 'description', 'access', 'strategy', 'browser', 'args',
                     ...(isStructured ? ['columns', 'domain'] : [])],
                 title: 'opencli/list',
                 source: 'opencli list',
@@ -489,6 +505,30 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(renderVerifyReport(r));
         process.exitCode = r.ok ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR;
     });
+    program
+        .command('convention-audit')
+        .description('Scan adapters for agent-native convention violations')
+        .argument('[target]', 'site or site/name')
+        .option('--site <site>', 'Limit audit to one site')
+        .option('-f, --format <fmt>', 'Output format: table, json, yaml', 'table')
+        .option('--strict', 'Exit non-zero when violations are found', false)
+        .action(async (target, opts) => {
+        const { runConventionAudit, renderConventionAuditText } = await import('./convention-audit.js');
+        const report = runConventionAudit({
+            projectRoot: findPackageRoot(CLI_FILE),
+            target,
+            site: opts.site,
+        });
+        const fmt = String(opts.format ?? 'table').toLowerCase();
+        if (fmt === 'json' || fmt === 'yaml' || fmt === 'yml') {
+            renderOutput(report, { fmt });
+        }
+        else {
+            console.log(renderConventionAuditText(report));
+        }
+        if (opts.strict && !report.ok)
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+    });
     // ── Built-in: browser (browser control for Claude Code skill) ───────────────
     //
     // Make websites accessible for AI agents.
@@ -542,6 +582,19 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             },
         }, null, 2));
     }
+    function isJavaScriptDialogMessage(message) {
+        const normalized = message.toLowerCase();
+        return normalized.includes('javascript dialog');
+    }
+    function emitJavaScriptDialogError(message) {
+        console.log(JSON.stringify({
+            error: {
+                code: 'javascript_dialog_open',
+                message,
+                hint: 'Handle the modal first: opencli browser dialog accept (or dismiss). Use --text for prompt dialogs.',
+            },
+        }, null, 2));
+    }
     /** Wrap browser actions with error handling and optional --json output */
     function browserAction(fn) {
         return async (...args) => {
@@ -560,7 +613,10 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                         log.error(`Hint: ${err.hint}`);
                 }
                 else if (err instanceof BrowserCommandError) {
-                    if (err.code) {
+                    if (isJavaScriptDialogMessage(err.message)) {
+                        emitJavaScriptDialogError(err.message);
+                    }
+                    else if (err.code) {
                         console.log(JSON.stringify({
                             error: {
                                 code: err.code,
@@ -582,7 +638,11 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                 }
                 else {
                     const msg = getErrorMessage(err);
-                    if (msg.includes('attach failed') || msg.includes('chrome-extension://')) {
+                    if (isJavaScriptDialogMessage(msg)) {
+                        emitJavaScriptDialogError(msg);
+                        log.error(msg);
+                    }
+                    else if (msg.includes('attach failed') || msg.includes('chrome-extension://')) {
                         log.error(`Browser attach failed — another extension may be interfering. Try disabling 1Password.`);
                     }
                     else {
@@ -1295,6 +1355,60 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         await page.pressKey(key);
         console.log(`Pressed: ${key}`);
     }));
+    const browserDialog = browser
+        .command('dialog')
+        .description('Handle a blocking JavaScript alert/confirm/prompt dialog');
+    addBrowserTabOption(browserDialog.command('accept')
+        .option('--text <text>', 'Prompt text to submit for prompt() dialogs')
+        .description('Accept the currently open JavaScript dialog'))
+        .action(browserAction(async (page, opts) => {
+        if (!page.handleJavaScriptDialog) {
+            throw new Error('This browser session does not support JavaScript dialog handling');
+        }
+        try {
+            await page.handleJavaScriptDialog(true, opts?.text);
+        }
+        catch (err) {
+            const message = getErrorMessage(err);
+            if (message.toLowerCase().includes('no dialog')) {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'no_javascript_dialog',
+                        message: 'No JavaScript dialog is currently open.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            throw err;
+        }
+        console.log(JSON.stringify({ handled: true, action: 'accept', ...(opts?.text !== undefined && { text: opts.text }) }, null, 2));
+    }));
+    addBrowserTabOption(browserDialog.command('dismiss')
+        .description('Dismiss the currently open JavaScript dialog'))
+        .action(browserAction(async (page) => {
+        if (!page.handleJavaScriptDialog) {
+            throw new Error('This browser session does not support JavaScript dialog handling');
+        }
+        try {
+            await page.handleJavaScriptDialog(false);
+        }
+        catch (err) {
+            const message = getErrorMessage(err);
+            if (message.toLowerCase().includes('no dialog')) {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'no_javascript_dialog',
+                        message: 'No JavaScript dialog is currently open.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            throw err;
+        }
+        console.log(JSON.stringify({ handled: true, action: 'dismiss' }, null, 2));
+    }));
     // ── Wait commands ──
     addBrowserTabOption(browser.command('wait'))
         .argument('<type>', 'selector, text, time, or xhr')
@@ -1741,6 +1855,8 @@ cli({
   site: '${site}',
   name: '${command}',
   description: '', // TODO: describe what this command does
+  access: 'read',  // TODO: 'read' for queries, 'write' for remote/account state changes
+  example: 'opencli ${site} ${command} -f yaml',
   domain: '${domain}',
   strategy: Strategy.PUBLIC, // TODO: PUBLIC (no auth), COOKIE (needs login), UI (DOM interaction)
   browser: false,            // TODO: set true if needs browser
@@ -1759,6 +1875,7 @@ cli({
             fs.mkdirSync(dir, { recursive: true });
             fs.writeFileSync(filePath, template, 'utf-8');
             console.log(`Created: ${filePath}`);
+            console.log('First time on this site? Run: opencli browser analyze <url>');
             console.log(`Edit the file to implement your adapter, then run: opencli browser verify ${name}`);
         }
         catch (err) {
@@ -1773,6 +1890,7 @@ cli({
         .option('--update-fixture', 'Overwrite an existing fixture with one derived from current output')
         .option('--no-fixture', 'Ignore any fixture file for this run (no value-level validation)')
         .option('--strict-memory', 'Fail (not just warn) when ~/.opencli/sites/<site>/endpoints.json or notes.md is missing')
+        .option('--seed-args <value>', 'Seed args when no fixture exists; use JSON array/object for multiple args or flags')
         .option('--trace <mode>', 'Trace capture for the adapter subprocess: off, on, retain-on-failure', 'off')
         .description('Execute an adapter and validate output; uses fixture at ~/.opencli/sites/<site>/verify/<cmd>.json when present')
         .action(async (name, opts = {}) => {
@@ -1790,7 +1908,7 @@ cli({
                 return;
             }
             const { execFileSync } = await import('node:child_process');
-            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs } = await import('./browser/verify-fixture.js');
+            const { loadFixture, writeFixture, deriveFixture, validateRows, validateRowShape, fixturePath, expandFixtureArgs, parseSeedArgs } = await import('./browser/verify-fixture.js');
             const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.js`);
             if (!fs.existsSync(filePath)) {
                 console.error(`Adapter not found: ${filePath}`);
@@ -1807,9 +1925,10 @@ cli({
             //   - array form    ["123", "--limit", "3"]   → verbatim (for positional subjects)
             const adapterSrc = fs.readFileSync(filePath, 'utf-8');
             const hasLimitArg = /['"]limit['"]/.test(adapterSrc);
-            const fixtureArgs = fixture?.args;
-            const cliArgs = expandFixtureArgs(fixtureArgs);
-            if (cliArgs.length === 0 && hasLimitArg)
+            const seedArgs = parseSeedArgs(opts.seedArgs);
+            const explicitArgs = fixture?.args ?? seedArgs;
+            const cliArgs = expandFixtureArgs(explicitArgs);
+            if (explicitArgs === undefined && cliArgs.length === 0 && hasLimitArg)
                 cliArgs.push('--limit', '3');
             const traceArgs = opts.trace && opts.trace !== 'off' ? ['--trace', opts.trace] : [];
             const argDisplay = [...cliArgs, ...traceArgs].join(' ');
@@ -1851,6 +1970,20 @@ cli({
             }
             console.log(renderVerifyPreview(rows));
             console.log(`\n  → ${rows.length} row${rows.length === 1 ? '' : 's'}`);
+            const shapeFailures = validateRowShape(rows);
+            if (shapeFailures.length > 0) {
+                console.log(`\n  ✗ Adapter output violates row shape conventions:`);
+                for (const f of shapeFailures.slice(0, 20)) {
+                    const where = f.rowIndex !== undefined ? `row[${f.rowIndex}] ` : '';
+                    console.log(`    - [${f.rule}] ${where}${f.detail}`);
+                }
+                if (shapeFailures.length > 20) {
+                    console.log(`    ... and ${shapeFailures.length - 20} more failure(s)`);
+                }
+                console.log(`\n  Keep rows agent-native: <=12 top-level keys, nesting depth <=1, and id-shaped fields at top level.`);
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
             // ── Fixture handling ───────────────────────────────────────────
             if (opts.writeFixture || opts.updateFixture) {
                 if (fixture && !opts.updateFixture) {
@@ -1858,10 +1991,10 @@ cli({
                     console.log(`  Use --update-fixture to overwrite.`);
                 }
                 else {
-                    const seedArgs = fixtureArgs !== undefined
-                        ? fixtureArgs
+                    const fixtureArgs = explicitArgs !== undefined
+                        ? explicitArgs
                         : (hasLimitArg ? { limit: 3 } : undefined);
-                    const derived = deriveFixture(rows, seedArgs);
+                    const derived = deriveFixture(rows, fixtureArgs);
                     const p = writeFixture(site, command, derived);
                     console.log(`\n  ${fixture ? '↻ Updated' : '✎ Wrote'} fixture: ${p}`);
                     console.log(`  Review and hand-tune the derived expectations (add patterns / notEmpty, tighten rowCount).`);
@@ -2404,7 +2537,13 @@ cli({
     // ── Dynamic adapter commands ──────────────────────────────────────────────
     const siteGroups = new Map();
     siteGroups.set('antigravity', antigravityCmd);
-    registerAllCommands(program, siteGroups);
+    const siteNames = registerAllCommands(program, siteGroups);
+    applyRootSubcommandSummaries(program);
+    const siteNameSet = new Set(siteNames);
+    program.configureHelp({
+        visibleCommands: (command) => command.commands.filter(child => command !== program || !siteNameSet.has(child.name())),
+    });
+    installStructuredHelp(program, () => rootHelpData(program, siteNames), () => formatRootAdapterHelpText(siteNames));
     // ── 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

@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { cli, getRegistry, Strategy } from './registry.js';
 import { BrowserCommandError } from './browser/daemon-client.js';
 import { TargetError } from './browser/target-errors.js';
 import { PKG_VERSION } from './version.js';
@@ -38,6 +40,130 @@ vi.mock('node:child_process', async () => {
     };
 });
 import { createProgram, findPackageRoot, normalizeVerifyRows, renderVerifyPreview, resolveBrowserVerifyInvocation, selectFreshByTimestamp } from './cli.js';
+describe('createProgram root help descriptions', () => {
+    function descriptionFor(program, name) {
+        return program.commands.find(cmd => cmd.name() === name)?.description();
+    }
+    it('summarizes built-in command groups with their subcommands', () => {
+        const program = createProgram('', '');
+        expect(descriptionFor(program, 'browser')).toContain('open');
+        expect(descriptionFor(program, 'browser')).toContain('type');
+        expect(descriptionFor(program, 'browser')).toContain('verify');
+        expect(descriptionFor(program, 'browser')).not.toContain('Browser control');
+        expect(descriptionFor(program, 'plugin')).toBe('create, install, list, uninstall, update');
+        expect(descriptionFor(program, 'adapter')).toBe('eject, reset, status');
+        expect(descriptionFor(program, 'profile')).toBe('list, rename, use');
+        expect(descriptionFor(program, 'daemon')).toBe('restart, status, stop');
+        expect(descriptionFor(program, 'external')).toBe('install, list, register');
+    });
+    it('keeps leaf command descriptions unchanged', () => {
+        const program = createProgram('', '');
+        expect(descriptionFor(program, 'list')).toBe('List all available CLI commands');
+        expect(descriptionFor(program, 'doctor')).toBe('Diagnose opencli browser bridge connectivity');
+    });
+    it('keeps site adapters out of root commands and lists sites in the root help tail', () => {
+        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,
+            });
+            cli({
+                site: 'youtube',
+                name: 'search',
+                access: 'read',
+                description: 'Search YouTube',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+            });
+            const program = createProgram('', '');
+            const help = program.helpInformation();
+            expect(help).toContain('Site adapters (2):');
+            expect(help).toContain('bilibili, youtube');
+            expect(help).toContain("opencli <site> --help -f yaml");
+            expect(help).not.toMatch(/\n  bilibili\s+hot/);
+            expect(help).not.toMatch(/\n  youtube\s+search/);
+        }
+        finally {
+            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);
+        const argv = process.argv;
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+            });
+            const program = createProgram('', '');
+            process.argv = ['node', 'opencli', '--help', '-f', 'yaml'];
+            const data = yaml.load(program.helpInformation());
+            expect(data.site_adapters.count).toBe(1);
+            expect(data.site_adapters.sites).toEqual(['bilibili']);
+            expect(data.commands.map((cmd) => cmd.name)).toContain('list');
+            expect(data.commands.map((cmd) => cmd.name)).not.toContain('bilibili');
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('renders per-site structured help with all commands, access, args, and examples', () => {
+        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',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            expect(site).toBeTruthy();
+            process.argv = ['node', 'opencli', 'bilibili', '--help', '-f', 'yaml'];
+            const data = yaml.load(site.helpInformation());
+            expect(data.site).toBe('bilibili');
+            expect(data.commands).toMatchObject([
+                {
+                    name: 'hot',
+                    access: 'read',
+                    description: 'Bilibili hot videos',
+                    example: 'opencli bilibili hot -f yaml',
+                    args: [{ name: 'limit', type: 'int', default: 20 }],
+                },
+            ]);
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+});
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
         const projectRoot = path.join('repo-root');
@@ -151,6 +277,97 @@ describe('browser verify', () => {
             fs.rmSync(fakeHome, { recursive: true, force: true });
         }
     });
+    it('uses --seed-args when no fixture args exist', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-seed-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        try {
+            const adapterDir = path.join(fakeHome, '.opencli', 'clis', 'hn');
+            fs.mkdirSync(adapterDir, { recursive: true });
+            fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture', '--seed-args', 'opencli-verify']);
+            expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+            const [, execArgs] = mockExecFileSync.mock.calls[0];
+            expect(execArgs.slice(-5)).toEqual(['hn', 'top', 'opencli-verify', '--format', 'json']);
+        }
+        finally {
+            if (originalHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = originalHome;
+            if (originalUserProfile === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = originalUserProfile;
+            fs.rmSync(fakeHome, { recursive: true, force: true });
+        }
+    });
+    it('writes --seed-args into a starter fixture', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-write-seed-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        mockExecFileSync.mockReturnValue(JSON.stringify([{ title: 'ok' }]));
+        try {
+            const adapterDir = path.join(fakeHome, '.opencli', 'clis', 'hn');
+            fs.mkdirSync(adapterDir, { recursive: true });
+            fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--write-fixture', '--seed-args', 'opencli-verify']);
+            const fixtureFile = path.join(fakeHome, '.opencli', 'sites', 'hn', 'verify', 'top.json');
+            const fixture = JSON.parse(fs.readFileSync(fixtureFile, 'utf-8'));
+            expect(fixture.args).toEqual(['opencli-verify']);
+            expect(fixture.expect.columns).toEqual(['title']);
+        }
+        finally {
+            if (originalHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = originalHome;
+            if (originalUserProfile === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = originalUserProfile;
+            fs.rmSync(fakeHome, { recursive: true, force: true });
+        }
+    });
+    it('fails before fixture handling when output row shape is not agent-native', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-shape-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        mockExecFileSync.mockReturnValue(JSON.stringify([{ title: 'ok', author: { user_id: 'u1' } }]));
+        const consoleLogSpy = vi.mocked(console.log);
+        consoleLogSpy.mockClear();
+        try {
+            const adapterDir = path.join(fakeHome, '.opencli', 'clis', 'hn');
+            fs.mkdirSync(adapterDir, { recursive: true });
+            fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture']);
+            expect(process.exitCode).toBe(1);
+            const output = consoleLogSpy.mock.calls.map((args) => args.join(' ')).join('\n');
+            expect(output).toContain('Adapter output violates row shape conventions');
+            expect(output).toContain('author.user_id');
+        }
+        finally {
+            consoleLogSpy.mockClear();
+            if (originalHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = originalHome;
+            if (originalUserProfile === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = originalUserProfile;
+            fs.rmSync(fakeHome, { recursive: true, force: true });
+        }
+    });
 });
 describe('profile list', () => {
     const stdoutSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
@@ -240,6 +457,7 @@ describe('browser tab targeting commands', () => {
             selectTab: vi.fn().mockResolvedValue(undefined),
             newTab: vi.fn().mockResolvedValue('tab-3'),
             closeTab: vi.fn().mockResolvedValue(undefined),
+            handleJavaScriptDialog: vi.fn().mockResolvedValue(undefined),
             frames: vi.fn().mockResolvedValue([
                 { index: 0, frameId: 'frame-1', url: 'https://x.example/embed', name: 'x-embed' },
             ]),
@@ -312,6 +530,25 @@ describe('browser tab targeting commands', () => {
         expect(out.error.code).toBe('bound_session_missing');
         expect(process.exitCode).toBeDefined();
     });
+    it('accepts JavaScript dialogs through the browser dialog command', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'dialog', 'accept', '--text', 'ok']);
+        expect(browserState.page?.handleJavaScriptDialog).toHaveBeenCalledWith(true, 'ok');
+        const out = lastJsonLog();
+        expect(out).toEqual({ handled: true, action: 'accept', text: 'ok' });
+    });
+    it('emits a structured error when a browser action is blocked by a JavaScript dialog', async () => {
+        browserState.page = {
+            ...browserState.page,
+            evaluate: vi.fn().mockRejectedValue(new Error('JavaScript dialog showing')),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'eval', 'document.title']);
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('javascript_dialog_open');
+        expect(out.error.hint).toContain('browser dialog accept');
+        expect(process.exitCode).toBeDefined();
+    });
     it('binds browser commands to an explicit target tab via --tab', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', 'eval', '--tab', 'tab-2', 'document.title']);

package/dist/src/commanderAdapter.d.ts

@@ -18,4 +18,4 @@ export declare function registerCommandToProgram(siteCmd: Command, cmd: CliComma
 /**
  * Register all commands from the registry onto a Commander program.
  */
-export declare function registerAllCommands(program: Command, siteGroups: Map<string, Command>): void;
+export declare function registerAllCommands(program: Command, siteGroups: Map<string, Command>): string[];

package/dist/src/commanderAdapter.js

@@ -15,6 +15,7 @@ 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 { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
 /**
  * Register a single CliCommand as a Commander subcommand.
@@ -22,8 +23,7 @@ import { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
 export function registerCommandToProgram(siteCmd, cmd) {
     if (siteCmd.commands.some((c) => c.name() === cmd.name))
         return;
-    const deprecatedSuffix = cmd.deprecated ? ' [deprecated]' : '';
-    const subCmd = siteCmd.command(cmd.name).description(`${cmd.description}${deprecatedSuffix}`);
+    const subCmd = siteCmd.command(cmd.name).description(formatSiteCommandDescription(cmd));
     if (cmd.aliases?.length)
         subCmd.aliases(cmd.aliases);
     // Register positional args first, then named options
@@ -49,7 +49,7 @@ 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);
-    subCmd.addHelpText('after', formatRegistryHelpText(cmd));
+    installStructuredHelp(subCmd, () => commandHelpData(cmd), () => formatRegistryHelpText(cmd));
     subCmd.action(async (...actionArgs) => {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
         const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
@@ -161,15 +161,25 @@ function renderError(err, cmdName, verbose, traceMode) {
  */
 export function registerAllCommands(program, siteGroups) {
     const seen = new Set();
+    const commandsBySite = new Map();
     for (const [, cmd] of getRegistry()) {
         if (seen.has(cmd))
             continue;
         seen.add(cmd);
-        let siteCmd = siteGroups.get(cmd.site);
+        const commands = commandsBySite.get(cmd.site) ?? [];
+        commands.push(cmd);
+        commandsBySite.set(cmd.site, commands);
+    }
+    for (const [site, commands] of commandsBySite) {
+        let siteCmd = siteGroups.get(site);
         if (!siteCmd) {
-            siteCmd = program.command(cmd.site).description(`${cmd.site} commands`);
-            siteGroups.set(cmd.site, siteCmd);
+            siteCmd = program.command(site);
+            siteGroups.set(site, siteCmd);
+        }
+        for (const cmd of commands) {
+            registerCommandToProgram(siteCmd, cmd);
         }
-        registerCommandToProgram(siteCmd, cmd);
+        installStructuredHelp(siteCmd, () => siteHelpData(site, commands));
     }
+    return [...commandsBySite.keys()].sort((a, b) => a.localeCompare(b));
 }