@jackwener/opencli 1.7.11 → 1.7.13

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,214 @@ 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('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);
+        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');
@@ -209,6 +419,39 @@ describe('browser verify', () => {
             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(() => { });
@@ -298,6 +541,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' },
             ]),
@@ -370,6 +614,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']);
@@ -1445,6 +1708,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 () => {
@@ -1542,6 +1815,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.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 : {};
@@ -89,11 +89,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,
@@ -161,15 +156,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));
 }

package/dist/src/commanderAdapter.test.js

@@ -19,7 +19,7 @@ import { registerCommandToProgram } from './commanderAdapter.js';
 describe('commanderAdapter arg passing', () => {
     const cmd = {
         site: 'paperreview',
-        name: 'submit',
+        name: 'submit', access: 'read',
         description: 'Submit a PDF',
         browser: false,
         args: [
@@ -86,7 +86,7 @@ describe('commanderAdapter arg passing', () => {
 describe('commanderAdapter boolean alias support', () => {
     const cmd = {
         site: 'reddit',
-        name: 'save',
+        name: 'save', access: 'read',
         description: 'Save a post',
         browser: false,
         args: [
@@ -125,7 +125,7 @@ describe('commanderAdapter boolean alias support', () => {
 describe('commanderAdapter value-required optional options', () => {
     const cmd = {
         site: 'instagram',
-        name: 'post',
+        name: 'post', access: 'read',
         description: 'Post to Instagram',
         browser: true,
         args: [
@@ -168,6 +168,7 @@ describe('commanderAdapter command aliases', () => {
     const cmd = {
         site: 'notebooklm',
         name: 'get',
+        access: 'read',
         aliases: ['metadata'],
         description: 'Get notebook metadata',
         browser: false,
@@ -203,7 +204,7 @@ describe('commanderAdapter validation preparation', () => {
         const siteCmd = program.command('test');
         registerCommandToProgram(siteCmd, {
             site: 'test',
-            name: 'run',
+            name: 'run', access: 'read',
             description: 'Run test command',
             browser: false,
             args: [{ name: 'count', default: '1', help: 'Count' }],
@@ -218,7 +219,7 @@ describe('commanderAdapter validation preparation', () => {
 describe('commanderAdapter default formats', () => {
     const cmd = {
         site: 'gemini',
-        name: 'ask',
+        name: 'ask', access: 'read',
         description: 'Ask Gemini',
         browser: false,
         args: [],
@@ -251,7 +252,7 @@ describe('commanderAdapter default formats', () => {
 describe('commanderAdapter error envelope output', () => {
     const cmd = {
         site: 'xiaohongshu',
-        name: 'note',
+        name: 'note', access: 'read',
         description: 'Read one note',
         browser: false,
         args: [
@@ -278,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/convention-audit.d.ts

@@ -0,0 +1,50 @@
+export type ConventionRuleId = 'silent-column-drop' | 'camelCase-in-columns' | 'missing-access-metadata' | 'silent-clamp' | 'silent-empty-fallback' | 'silent-sentinel' | 'write-without-delete-pair';
+type ManifestArg = {
+    name?: string;
+    positional?: boolean;
+    required?: boolean;
+    help?: string;
+};
+export type ManifestCommand = {
+    site?: string;
+    name?: string;
+    access?: string;
+    args?: ManifestArg[];
+    columns?: string[];
+    modulePath?: string;
+    sourceFile?: string;
+};
+export type ConventionViolation = {
+    rule: ConventionRuleId;
+    site: string;
+    name: string;
+    command: string;
+    message: string;
+    file?: string;
+    line?: number;
+    details?: Record<string, unknown>;
+};
+export type ConventionCategory = {
+    rule: ConventionRuleId;
+    count: number;
+    violations: ConventionViolation[];
+};
+export type ConventionAuditReport = {
+    ok: boolean;
+    summary: {
+        commands: number;
+        sites: number;
+        files_scanned: number;
+        violations: number;
+    };
+    categories: ConventionCategory[];
+};
+export type ConventionAuditOptions = {
+    projectRoot: string;
+    manifestPath?: string;
+    target?: string;
+    site?: string;
+};
+export declare function runConventionAudit(opts: ConventionAuditOptions): ConventionAuditReport;
+export declare function renderConventionAuditText(report: ConventionAuditReport): string;
+export {};