@jackwener/opencli 1.7.11 → 1.7.13

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,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 { 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';
@@ -315,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,
@@ -388,10 +391,34 @@ 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';
 }
+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 +448,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 +517,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 +594,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 +625,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 +650,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 {
@@ -828,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'))
@@ -1253,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')
@@ -1295,6 +1402,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 +1902,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
@@ -1792,7 +1955,7 @@ cli({
                 return;
             }
             const { execFileSync } = await import('node:child_process');
-            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs, parseSeedArgs } = 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}`);
@@ -1854,6 +2017,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) {
@@ -1906,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
@@ -2407,7 +2584,31 @@ cli({
     // ── Dynamic adapter commands ──────────────────────────────────────────────
     const siteGroups = new Map();
     siteGroups.set('antigravity', antigravityCmd);
-    registerAllCommands(program, siteGroups);
+    const siteNames = registerAllCommands(program, siteGroups);
+    applyRootSubcommandSummaries(program);
+    // ── 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 || !adapterNameSet.has(child.name())),
+    });
+    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.