@jackwener/opencli 1.1.0 → 1.1.1

package/dist/explore.js

@@ -210,6 +210,120 @@ const FRAMEWORK_DETECT_JS = detectFramework.toString();
 const STORE_DISCOVER_JS = discoverStores.toString();
 // ── Auto-Interaction (Fuzzing) ─────────────────────────────────────────────
 const INTERACT_FUZZ_JS = interactFuzz.toString();
+// ── Analysis helpers (extracted from exploreUrl) ───────────────────────────
+/** Filter, deduplicate, and score network endpoints. */
+function analyzeEndpoints(networkEntries) {
+    const seen = new Map();
+    for (const entry of networkEntries) {
+        if (!entry.url)
+            continue;
+        const ct = entry.contentType.toLowerCase();
+        if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm'))
+            continue;
+        if (entry.status && entry.status >= 400)
+            continue;
+        const pattern = urlToPattern(entry.url);
+        const key = `${entry.method}:${pattern}`;
+        if (seen.has(key))
+            continue;
+        const qp = [];
+        try {
+            new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
+                qp.push(k); });
+        }
+        catch { }
+        const ep = {
+            pattern, method: entry.method, url: entry.url, status: entry.status, contentType: ct,
+            queryParams: qp, hasSearchParam: qp.some(p => SEARCH_PARAMS.has(p)),
+            hasPaginationParam: qp.some(p => PAGINATION_PARAMS.has(p)),
+            hasLimitParam: qp.some(p => LIMIT_PARAMS.has(p)),
+            authIndicators: detectAuthIndicators(entry.requestHeaders),
+            responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
+            score: 0,
+        };
+        ep.score = scoreEndpoint(ep);
+        seen.set(key, ep);
+    }
+    const analyzed = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
+    return { analyzed, totalCount: seen.size };
+}
+/** Infer CLI capabilities from analyzed endpoints. */
+function inferCapabilitiesFromEndpoints(endpoints, stores, opts) {
+    const capabilities = [];
+    const usedNames = new Set();
+    for (const ep of endpoints.slice(0, 8)) {
+        let capName = inferCapabilityName(ep.url, opts.goal);
+        if (usedNames.has(capName)) {
+            const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
+            capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
+        }
+        usedNames.add(capName);
+        const cols = [];
+        if (ep.responseAnalysis) {
+            for (const role of ['title', 'url', 'author', 'score', 'time']) {
+                if (ep.responseAnalysis.detectedFields[role])
+                    cols.push(role);
+            }
+        }
+        const args = [];
+        if (ep.hasSearchParam)
+            args.push({ name: 'keyword', type: 'str', required: true });
+        args.push({ name: 'limit', type: 'int', required: false, default: 20 });
+        if (ep.hasPaginationParam)
+            args.push({ name: 'page', type: 'int', required: false, default: 1 });
+        const epStrategy = inferStrategy(ep.authIndicators);
+        let storeHint;
+        if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
+            for (const s of stores) {
+                const matchingAction = s.actions.find(a => capName.split('_').some(part => a.toLowerCase().includes(part)) ||
+                    a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get'));
+                if (matchingAction) {
+                    storeHint = { store: s.id, action: matchingAction };
+                    break;
+                }
+            }
+        }
+        capabilities.push({
+            name: capName, description: `${opts.site ?? detectSiteName(opts.url)} ${capName}`,
+            strategy: storeHint ? 'store-action' : epStrategy,
+            confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
+            itemPath: ep.responseAnalysis?.itemPath ?? null,
+            recommendedColumns: cols.length ? cols : ['title', 'url'],
+            recommendedArgs: args,
+            ...(storeHint ? { storeHint } : {}),
+        });
+    }
+    const allAuth = new Set(endpoints.flatMap(ep => ep.authIndicators));
+    const topStrategy = allAuth.has('signature') ? 'intercept'
+        : allAuth.has('bearer') || allAuth.has('csrf') ? 'header'
+            : allAuth.size === 0 ? 'public' : 'cookie';
+    return { capabilities, topStrategy, authIndicators: [...allAuth] };
+}
+/** Write explore artifacts (manifest, endpoints, capabilities, auth, stores) to disk. */
+async function writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores) {
+    await fs.promises.mkdir(targetDir, { recursive: true });
+    const tasks = [
+        fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
+            site: result.site, target_url: result.target_url, final_url: result.final_url, title: result.title,
+            framework: result.framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
+            top_strategy: result.top_strategy, explored_at: new Date().toISOString(),
+        }, null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
+            pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
+            contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
+            itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
+            detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
+        })), null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(result.capabilities, null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
+            top_strategy: result.top_strategy, indicators: result.auth_indicators, framework: result.framework,
+        }, null, 2)),
+    ];
+    if (stores.length > 0) {
+        tasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
+    }
+    await Promise.all(tasks);
+}
 // ── Main explore function ──────────────────────────────────────────────────
 export async function exploreUrl(url, opts) {
     const waitSeconds = opts.waitSeconds ?? 3.0;
@@ -301,120 +415,20 @@ export async function exploreUrl(url, opts) {
                 }
                 catch { }
             }
-            // Step 7: Analyze endpoints
-            const seen = new Map();
-            for (const entry of networkEntries) {
-                if (!entry.url)
-                    continue;
-                const ct = entry.contentType.toLowerCase();
-                if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm'))
-                    continue;
-                if (entry.status && entry.status >= 400)
-                    continue;
-                const pattern = urlToPattern(entry.url);
-                const key = `${entry.method}:${pattern}`;
-                if (seen.has(key))
-                    continue;
-                const qp = [];
-                try {
-                    new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
-                        qp.push(k); });
-                }
-                catch { }
-                const ep = {
-                    pattern, method: entry.method, url: entry.url, status: entry.status, contentType: ct,
-                    queryParams: qp, hasSearchParam: qp.some(p => SEARCH_PARAMS.has(p)),
-                    hasPaginationParam: qp.some(p => PAGINATION_PARAMS.has(p)),
-                    hasLimitParam: qp.some(p => LIMIT_PARAMS.has(p)),
-                    authIndicators: detectAuthIndicators(entry.requestHeaders),
-                    responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
-                    score: 0,
-                };
-                ep.score = scoreEndpoint(ep);
-                seen.set(key, ep);
-            }
-            const analyzedEndpoints = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
-            // Step 8: Infer capabilities
-            const capabilities = [];
-            const usedNames = new Set();
-            for (const ep of analyzedEndpoints.slice(0, 8)) {
-                let capName = inferCapabilityName(ep.url, opts.goal);
-                if (usedNames.has(capName)) {
-                    const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
-                    capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
-                }
-                usedNames.add(capName);
-                const cols = [];
-                if (ep.responseAnalysis) {
-                    for (const role of ['title', 'url', 'author', 'score', 'time']) {
-                        if (ep.responseAnalysis.detectedFields[role])
-                            cols.push(role);
-                    }
-                }
-                const args = [];
-                if (ep.hasSearchParam)
-                    args.push({ name: 'keyword', type: 'str', required: true });
-                args.push({ name: 'limit', type: 'int', required: false, default: 20 });
-                if (ep.hasPaginationParam)
-                    args.push({ name: 'page', type: 'int', required: false, default: 1 });
-                // Link store actions to capabilities when store-action strategy is recommended
-                const epStrategy = inferStrategy(ep.authIndicators);
-                let storeHint;
-                if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
-                    // Try to find a store/action that matches this endpoint's purpose
-                    for (const s of stores) {
-                        const matchingAction = s.actions.find(a => capName.split('_').some(part => a.toLowerCase().includes(part)) ||
-                            a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get'));
-                        if (matchingAction) {
-                            storeHint = { store: s.id, action: matchingAction };
-                            break;
-                        }
-                    }
-                }
-                capabilities.push({
-                    name: capName, description: `${opts.site ?? detectSiteName(url)} ${capName}`,
-                    strategy: storeHint ? 'store-action' : epStrategy,
-                    confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
-                    itemPath: ep.responseAnalysis?.itemPath ?? null,
-                    recommendedColumns: cols.length ? cols : ['title', 'url'],
-                    recommendedArgs: args,
-                    ...(storeHint ? { storeHint } : {}),
-                });
-            }
-            // Step 9: Determine overall auth strategy
-            const allAuth = new Set(analyzedEndpoints.flatMap(ep => ep.authIndicators));
-            const topStrategy = allAuth.has('signature') ? 'intercept' : allAuth.has('bearer') || allAuth.has('csrf') ? 'header' : allAuth.size === 0 ? 'public' : 'cookie';
+            // Step 7+8: Analyze endpoints and infer capabilities
+            const { analyzed: analyzedEndpoints, totalCount } = analyzeEndpoints(networkEntries);
+            const { capabilities, topStrategy, authIndicators } = inferCapabilitiesFromEndpoints(analyzedEndpoints, stores, { site: opts.site, goal: opts.goal, url });
+            // Step 9: Assemble result and write artifacts
             const siteName = opts.site ?? detectSiteName(metadata.url || url);
             const targetDir = opts.outDir ?? path.join('.opencli', 'explore', siteName);
-            await fs.promises.mkdir(targetDir, { recursive: true });
             const result = {
                 site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
                 framework, stores, top_strategy: topStrategy,
-                endpoint_count: analyzedEndpoints.length + [...seen.values()].filter(ep => ep.score < 5).length,
+                endpoint_count: totalCount,
                 api_endpoint_count: analyzedEndpoints.length,
-                capabilities, auth_indicators: [...allAuth],
+                capabilities, auth_indicators: authIndicators,
             };
-            // Write artifacts
-            const writeTasks = [];
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
-                site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
-                framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
-                top_strategy: topStrategy, explored_at: new Date().toISOString(),
-            }, null, 2)));
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
-                pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
-                contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
-                itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
-                detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
-            })), null, 2)));
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(capabilities, null, 2)));
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
-                top_strategy: topStrategy, indicators: [...allAuth], framework,
-            }, null, 2)));
-            if (stores.length > 0) {
-                writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
-            }
-            await Promise.all(writeTasks);
+            await writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores);
             return { ...result, out_dir: targetDir };
         })(), { timeout: exploreTimeout, label: `Explore ${url}` });
     }, { workspace: opts.workspace });

package/dist/external-clis.yaml

@@ -0,0 +1,48 @@
+- name: gh
+  binary: gh
+  description: "GitHub CLI — repos, PRs, issues, releases, gists"
+  homepage: "https://cli.github.com"
+  tags: [github, git, dev]
+  install:
+    mac: "brew install gh"
+
+- name: obsidian
+  binary: obsidian
+  description: "Obsidian vault management — notes, search, tags, tasks, sync"
+  homepage: "https://obsidian.md/help/cli"
+  tags: [notes, knowledge, markdown]
+  install:
+    mac: "brew install --cask obsidian"
+
+- name: readwise
+  binary: readwise
+  description: "Readwise & Reader CLI — highlights, annotations, reading list"
+  homepage: "https://github.com/readwiseio/readwise-cli"
+  tags: [reading, highlights]
+  install:
+    default: "npm install -g @readwiseio/readwise-cli"
+
+- name: kubectl
+  binary: kubectl
+  description: "Kubernetes command-line tool"
+  homepage: "https://kubernetes.io/docs/reference/kubectl/"
+  tags: [kubernetes, k8s, devops]
+  install:
+    mac: "brew install kubectl"
+
+- name: docker
+  binary: docker
+  description: "Docker command-line interface"
+  homepage: "https://docs.docker.com/engine/reference/commandline/cli/"
+  tags: [docker, containers, devops]
+  install:
+    mac: "brew install --cask docker"
+
+- name: gws
+  binary: gws
+  description: "Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar"
+  homepage: "https://github.com/nicholasgasior/gws"
+  tags: [google, docs, sheets, drive, workspace]
+  install:
+    mac: "brew install gws"
+    default: "npm install -g @nicholasgasior/gws"

package/dist/external.d.ts

@@ -16,5 +16,10 @@ export declare function loadExternalClis(): ExternalCliConfig[];
 export declare function isBinaryInstalled(binary: string): boolean;
 export declare function getInstallCmd(installConfig?: ExternalCliInstall): string | null;
 export declare function installExternalCli(cli: ExternalCliConfig): boolean;
-export declare function executeExternalCli(name: string, args: string[]): Promise<void>;
-export declare function registerExternalCli(name: string, binary?: string, install?: string, description?: string): void;
+export declare function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void;
+export interface RegisterOptions {
+    binary?: string;
+    install?: string;
+    description?: string;
+}
+export declare function registerExternalCli(name: string, opts?: RegisterOptions): void;

package/dist/external.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { spawnSync, execSync } from 'node:child_process';
+import { spawnSync, execSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
@@ -45,8 +45,7 @@ export function loadExternalClis() {
 export function isBinaryInstalled(binary) {
     try {
         const isWindows = os.platform() === 'win32';
-        const cmd = isWindows ? 'where' : 'command -v';
-        execSync(`${cmd} ${binary}`, { stdio: 'ignore' });
+        execFileSync(isWindows ? 'where' : 'which', [binary], { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -92,8 +91,8 @@ export function installExternalCli(cli) {
         return false;
     }
 }
-export async function executeExternalCli(name, args) {
-    const configs = loadExternalClis();
+export function executeExternalCli(name, args, preloaded) {
+    const configs = preloaded ?? loadExternalClis();
     const cli = configs.find((c) => c.name === name);
     if (!cli) {
         throw new Error(`External CLI '${name}' not found in registry.`);
@@ -107,8 +106,7 @@ export async function executeExternalCli(name, args) {
             return;
         }
     }
-    // 3. Passthrough execution
-    // We use spawnSync to properly inherit stdio and block until completion
+    // 3. Passthrough execution with stdio inherited
     const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
     if (result.error) {
         console.error(chalk.red(`Failed to execute '${cli.binary}': ${result.error.message}`));
@@ -119,7 +117,7 @@ export async function executeExternalCli(name, args) {
         process.exitCode = result.status;
     }
 }
-export function registerExternalCli(name, binary, install, description) {
+export function registerExternalCli(name, opts) {
     const userPath = getUserRegistryPath();
     const configDir = path.dirname(userPath);
     if (!fs.existsSync(configDir)) {
@@ -138,14 +136,13 @@ export function registerExternalCli(name, binary, install, description) {
     const existingIndex = items.findIndex((c) => c.name === name);
     const newItem = {
         name,
-        binary: binary || name,
+        binary: opts?.binary || name,
     };
-    if (description)
-        newItem.description = description;
-    if (install)
-        newItem.install = { default: install };
+    if (opts?.description)
+        newItem.description = opts.description;
+    if (opts?.install)
+        newItem.install = { default: opts.install };
     if (existingIndex >= 0) {
-        // Merge
         items[existingIndex] = { ...items[existingIndex], ...newItem };
         console.log(chalk.green(`Updated '${name}' in user registry.`));
     }

package/dist/main.js

@@ -5,7 +5,7 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverClis } from './engine.js';
+import { discoverClis } from './discovery.js';
 import { getCompletions } from './completion.js';
 import { runCli } from './cli.js';
 const __filename = fileURLToPath(import.meta.url);

package/dist/pipeline/steps/browser.js

@@ -4,8 +4,14 @@
  */
 import { render } from '../template.js';
 export async function stepNavigate(page, params, data, args) {
-    const url = render(params, { args, data });
-    await page.goto(String(url));
+    if (typeof params === 'object' && params && 'url' in params) {
+        const url = String(render(params.url, { args, data }));
+        await page.goto(url, { waitUntil: params.waitUntil, settleMs: params.settleMs });
+    }
+    else {
+        const url = render(params, { args, data });
+        await page.goto(String(url));
+    }
     return data;
 }
 export async function stepClick(page, params, data, args) {

package/dist/registry.d.ts

@@ -49,3 +49,5 @@ export declare function getRegistry(): Map<string, CliCommand>;
 export declare function fullName(cmd: CliCommand): string;
 export declare function strategyLabel(cmd: CliCommand): string;
 export declare function registerCommand(cmd: CliCommand): void;
+export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';
+export type { SerializedArg } from './serialization.js';

package/dist/registry.js

@@ -43,3 +43,5 @@ export function strategyLabel(cmd) {
 export function registerCommand(cmd) {
     _registry.set(fullName(cmd), cmd);
 }
+// Re-export serialization helpers from their dedicated module
+export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';

package/dist/runtime.d.ts

@@ -1,4 +1,9 @@
 import type { IPage } from './types.js';
+/**
+ * Returns the appropriate browser factory based on environment config.
+ * Uses CDPBridge when OPENCLI_CDP_ENDPOINT is set, otherwise BrowserBridge.
+ */
+export declare function getBrowserFactory(): new () => IBrowserFactory;
 export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_EXPLORE_TIMEOUT: number;

package/dist/runtime.js

@@ -1,3 +1,11 @@
+import { BrowserBridge, CDPBridge } from './browser/index.js';
+/**
+ * Returns the appropriate browser factory based on environment config.
+ * Uses CDPBridge when OPENCLI_CDP_ENDPOINT is set, otherwise BrowserBridge.
+ */
+export function getBrowserFactory() {
+    return (process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge);
+}
 export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
 export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_COMMAND_TIMEOUT ?? '60', 10);
 export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_EXPLORE_TIMEOUT ?? '120', 10);

package/dist/serialization.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Serialization and formatting helpers for CLI commands and args.
+ *
+ * Used by the `list` command, Commander --help, and build-manifest.
+ * Separated from registry.ts to keep the registry focused on types + registration.
+ */
+import type { Arg, CliCommand } from './registry.js';
+export type SerializedArg = {
+    name: string;
+    type: string;
+    required: boolean;
+    positional: boolean;
+    choices: string[];
+    default: unknown;
+    help: string;
+};
+/** Stable arg schema — every field is always present (no sparse objects). */
+export declare function serializeArg(a: Arg): SerializedArg;
+/** Full command metadata for structured output (json/yaml). */
+export declare function serializeCommand(cmd: CliCommand): {
+    command: string;
+    site: string;
+    name: string;
+    description: string;
+    strategy: string;
+    browser: boolean;
+    args: SerializedArg[];
+    columns: string[];
+    domain: string | null;
+};
+/** Human-readable arg summary: `<required> [optional]` style. */
+export declare function formatArgSummary(args: Arg[]): string;
+/** Generate the --help appendix showing registry metadata not exposed by Commander. */
+export declare function formatRegistryHelpText(cmd: CliCommand): string;

package/dist/serialization.js

@@ -0,0 +1,63 @@
+/**
+ * Serialization and formatting helpers for CLI commands and args.
+ *
+ * Used by the `list` command, Commander --help, and build-manifest.
+ * Separated from registry.ts to keep the registry focused on types + registration.
+ */
+import { fullName, strategyLabel } from './registry.js';
+/** Stable arg schema — every field is always present (no sparse objects). */
+export function serializeArg(a) {
+    return {
+        name: a.name,
+        type: a.type ?? 'string',
+        required: !!a.required,
+        positional: !!a.positional,
+        choices: a.choices ?? [],
+        default: a.default ?? null,
+        help: a.help ?? '',
+    };
+}
+/** Full command metadata for structured output (json/yaml). */
+export function serializeCommand(cmd) {
+    return {
+        command: fullName(cmd),
+        site: cmd.site,
+        name: cmd.name,
+        description: cmd.description,
+        strategy: strategyLabel(cmd),
+        browser: !!cmd.browser,
+        args: cmd.args.map(serializeArg),
+        columns: cmd.columns ?? [],
+        domain: cmd.domain ?? null,
+    };
+}
+// ── Formatting ──────────────────────────────────────────────────────────────
+/** Human-readable arg summary: `<required> [optional]` style. */
+export function formatArgSummary(args) {
+    return args
+        .map(a => {
+        if (a.positional)
+            return a.required ? `<${a.name}>` : `[${a.name}]`;
+        return a.required ? `--${a.name}` : `[--${a.name}]`;
+    })
+        .join(' ');
+}
+/** Generate the --help appendix showing registry metadata not exposed by Commander. */
+export function formatRegistryHelpText(cmd) {
+    const lines = [];
+    const choicesArgs = cmd.args.filter(a => a.choices?.length);
+    for (const a of choicesArgs) {
+        const prefix = a.positional ? `<${a.name}>` : `--${a.name}`;
+        const def = a.default != null ? `  (default: ${a.default})` : '';
+        lines.push(`  ${prefix}: ${a.choices.join(', ')}${def}`);
+    }
+    const meta = [];
+    meta.push(`Strategy: ${strategyLabel(cmd)}`);
+    meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
+    if (cmd.domain)
+        meta.push(`Domain: ${cmd.domain}`);
+    lines.push(meta.join(' | '));
+    if (cmd.columns?.length)
+        lines.push(`Output columns: ${cmd.columns.join(', ')}`);
+    return '\n' + lines.join('\n') + '\n';
+}

package/dist/types.d.ts

@@ -5,7 +5,10 @@
  * instead of `any` for browser interactions.
  */
 export interface IPage {
-    goto(url: string): Promise<void>;
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
     evaluate(js: string): Promise<any>;
     getCookies(opts?: {
         domain?: string;

package/docs/.vitepress/config.mts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'vitepress'
 
 export default defineConfig({
-  base: '/',
+  base: '/docs/',
   title: 'OpenCLI',
   description: 'Make any website or Electron App your CLI — AI-powered, account-safe, self-healing.',
 
@@ -54,12 +54,19 @@ export default defineConfig({
                 { text: 'YouTube', link: '/adapters/browser/youtube' },
                 { text: 'Xueqiu', link: '/adapters/browser/xueqiu' },
                 { text: 'V2EX', link: '/adapters/browser/v2ex' },
+                { text: 'Bloomberg', link: '/adapters/browser/bloomberg' },
                 { text: 'LinkedIn', link: '/adapters/browser/linkedin' },
                 { text: 'Coupang', link: '/adapters/browser/coupang' },
                 { text: 'BOSS Zhipin', link: '/adapters/browser/boss' },
                 { text: 'Ctrip', link: '/adapters/browser/ctrip' },
                 { text: 'Reuters', link: '/adapters/browser/reuters' },
                 { text: 'SMZDM', link: '/adapters/browser/smzdm' },
+                { text: 'Jike', link: '/adapters/browser/jike' },
+                { text: 'Jimeng', link: '/adapters/browser/jimeng' },
+                { text: 'LINUX DO', link: '/adapters/browser/linux-do' },
+                { text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
+                { text: 'Grok', link: '/adapters/browser/grok' },
+                { text: 'WeRead', link: '/adapters/browser/weread' },
               ],
             },
             {
@@ -72,6 +79,12 @@ export default defineConfig({
                 { text: 'Apple Podcasts', link: '/adapters/browser/apple-podcasts' },
                 { text: 'Xiaoyuzhou', link: '/adapters/browser/xiaoyuzhou' },
                 { text: 'Yahoo Finance', link: '/adapters/browser/yahoo-finance' },
+                { text: 'arXiv', link: '/adapters/browser/arxiv' },
+                { text: 'Barchart', link: '/adapters/browser/barchart' },
+                { text: 'Hugging Face', link: '/adapters/browser/hf' },
+                { text: 'Sina Finance', link: '/adapters/browser/sinafinance' },
+                { text: 'Stack Overflow', link: '/adapters/browser/stackoverflow' },
+                { text: 'Wikipedia', link: '/adapters/browser/wikipedia' },
               ],
             },
             {
@@ -137,7 +150,6 @@ export default defineConfig({
                 { text: '快速开始', link: '/zh/guide/getting-started' },
                 { text: '安装', link: '/zh/guide/installation' },
                 { text: 'Browser Bridge', link: '/zh/guide/browser-bridge' },
-                { text: '问题排查', link: '/zh/guide/troubleshooting' },
               ],
             },
           ],
@@ -154,7 +166,6 @@ export default defineConfig({
               text: '开发者指南',
               items: [
                 { text: '贡献指南', link: '/zh/developer/contributing' },
-                { text: '测试', link: '/zh/developer/testing' },
               ],
             },
           ],

package/docs/adapters/browser/arxiv.md

@@ -0,0 +1,27 @@
+# arXiv
+
+**Mode**: 🌐 Public · **Domain**: `arxiv.org`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli arxiv search` | Search arXiv papers |
+| `opencli arxiv paper` | Get arXiv paper details by ID |
+
+## Usage Examples
+
+```bash
+# Search for papers
+opencli arxiv search "transformer attention" --limit 10
+
+# Get paper details by arXiv ID
+opencli arxiv paper 2301.00001
+
+# JSON output
+opencli arxiv search "LLM" -f json
+```
+
+## Prerequisites
+
+- No browser required — uses public arXiv API