@jackwener/opencli 1.0.6 → 1.1.1

package/dist/execution.js

@@ -0,0 +1,129 @@
+/**
+ * Command execution: validates args, manages browser sessions, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. Browser session lifecycle (if needed)
+ * 3. Domain pre-navigation for cookie/header strategies
+ * 4. Timeout enforcement
+ * 5. Lazy-loading of TS modules from manifest
+ */
+import { Strategy, getRegistry, fullName } from './registry.js';
+import { executePipeline } from './pipeline.js';
+import { AdapterLoadError } from './errors.js';
+import { shouldUseBrowserSession } from './capabilityRouting.js';
+import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
+/** Set of TS module paths that have been loaded */
+const _loadedModules = new Set();
+/**
+ * Validates and coerces arguments based on the command's Arg definitions.
+ */
+export function coerceAndValidateArgs(cmdArgs, kwargs) {
+    const result = { ...kwargs };
+    for (const argDef of cmdArgs) {
+        const val = result[argDef.name];
+        // 1. Check required
+        if (argDef.required && (val === undefined || val === null || val === '')) {
+            throw new Error(`Argument "${argDef.name}" is required.\n${argDef.help ? `Hint: ${argDef.help}` : ''}`);
+        }
+        if (val !== undefined && val !== null) {
+            // 2. Type coercion
+            if (argDef.type === 'int' || argDef.type === 'number') {
+                const num = Number(val);
+                if (Number.isNaN(num)) {
+                    throw new Error(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+                }
+                result[argDef.name] = num;
+            }
+            else if (argDef.type === 'boolean' || argDef.type === 'bool') {
+                if (typeof val === 'string') {
+                    const lower = val.toLowerCase();
+                    if (lower === 'true' || lower === '1')
+                        result[argDef.name] = true;
+                    else if (lower === 'false' || lower === '0')
+                        result[argDef.name] = false;
+                    else
+                        throw new Error(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+                }
+                else {
+                    result[argDef.name] = Boolean(val);
+                }
+            }
+            // 3. Choices validation
+            const coercedVal = result[argDef.name];
+            if (argDef.choices && argDef.choices.length > 0) {
+                if (!argDef.choices.map(String).includes(String(coercedVal))) {
+                    throw new Error(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+                }
+            }
+        }
+        else if (argDef.default !== undefined) {
+            result[argDef.name] = argDef.default;
+        }
+    }
+    return result;
+}
+/**
+ * Run a command's func or pipeline against a page.
+ */
+async function runCommand(cmd, page, kwargs, debug) {
+    // Lazy-load TS module on first execution (manifest fast-path)
+    const internal = cmd;
+    if (internal._lazy && internal._modulePath) {
+        const modulePath = internal._modulePath;
+        if (!_loadedModules.has(modulePath)) {
+            try {
+                await import(`file://${modulePath}`);
+                _loadedModules.add(modulePath);
+            }
+            catch (err) {
+                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${err.message}`, 'Check that the adapter file exists and has no syntax errors.');
+            }
+        }
+        // After loading, the module's cli() call will have updated the registry.
+        const updated = getRegistry().get(fullName(cmd));
+        if (updated?.func)
+            return updated.func(page, kwargs, debug);
+        if (updated?.pipeline)
+            return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+    }
+    if (cmd.func)
+        return cmd.func(page, kwargs, debug);
+    if (cmd.pipeline)
+        return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
+    throw new Error(`Command ${fullName(cmd)} has no func or pipeline`);
+}
+/**
+ * Execute a CLI command. Automatically manages browser sessions when needed.
+ *
+ * This is the unified entry point — callers don't need to care about
+ * whether the command requires a browser or not.
+ */
+export async function executeCommand(cmd, rawKwargs, debug = false) {
+    let kwargs;
+    try {
+        kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+    }
+    catch (err) {
+        throw new Error(`[Argument Validation Error]\n${err.message}`);
+    }
+    if (shouldUseBrowserSession(cmd)) {
+        const BrowserFactory = getBrowserFactory();
+        return browserSession(BrowserFactory, async (page) => {
+            // Cookie/header strategies require same-origin context for credentialed fetch.
+            if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
+                try {
+                    await page.goto(`https://${cmd.domain}`);
+                    await page.wait(2);
+                }
+                catch { }
+            }
+            return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                label: fullName(cmd),
+            });
+        }, { workspace: `site:${cmd.site}` });
+    }
+    // Non-browser commands run directly
+    return runCommand(cmd, null, kwargs, debug);
+}

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

@@ -0,0 +1,25 @@
+export interface ExternalCliInstall {
+    mac?: string;
+    linux?: string;
+    windows?: string;
+    default?: string;
+}
+export interface ExternalCliConfig {
+    name: string;
+    binary: string;
+    description?: string;
+    homepage?: string;
+    tags?: string[];
+    install?: ExternalCliInstall;
+}
+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[], 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

@@ -0,0 +1,156 @@
+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, execFileSync } from 'node:child_process';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+import { log } from './logger.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function getUserRegistryPath() {
+    const home = os.homedir();
+    return path.join(home, '.opencli', 'external-clis.yaml');
+}
+export function loadExternalClis() {
+    const configs = new Map();
+    // 1. Load built-in
+    const builtinPath = path.resolve(__dirname, 'external-clis.yaml');
+    try {
+        if (fs.existsSync(builtinPath)) {
+            const raw = fs.readFileSync(builtinPath, 'utf8');
+            const parsed = (yaml.load(raw) || []);
+            for (const item of parsed)
+                configs.set(item.name, item);
+        }
+    }
+    catch (err) {
+        log.warn(`Failed to parse built-in external-clis.yaml: ${err.message}`);
+    }
+    // 2. Load user custom
+    const userPath = getUserRegistryPath();
+    try {
+        if (fs.existsSync(userPath)) {
+            const raw = fs.readFileSync(userPath, 'utf8');
+            const parsed = (yaml.load(raw) || []);
+            for (const item of parsed) {
+                configs.set(item.name, item); // Overwrite built-in if duplicated
+            }
+        }
+    }
+    catch (err) {
+        log.warn(`Failed to parse user external-clis.yaml: ${err.message}`);
+    }
+    return Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+export function isBinaryInstalled(binary) {
+    try {
+        const isWindows = os.platform() === 'win32';
+        execFileSync(isWindows ? 'where' : 'which', [binary], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getInstallCmd(installConfig) {
+    if (!installConfig)
+        return null;
+    const platform = os.platform();
+    if (platform === 'darwin' && installConfig.mac)
+        return installConfig.mac;
+    if (platform === 'linux' && installConfig.linux)
+        return installConfig.linux;
+    if (platform === 'win32' && installConfig.windows)
+        return installConfig.windows;
+    if (installConfig.default)
+        return installConfig.default;
+    return null;
+}
+export function installExternalCli(cli) {
+    if (!cli.install) {
+        console.error(chalk.red(`No auto-install command configured for '${cli.name}'.`));
+        console.error(`Please install '${cli.binary}' manually.`);
+        return false;
+    }
+    const cmd = getInstallCmd(cli.install);
+    if (!cmd) {
+        console.error(chalk.red(`No install command for your platform (${os.platform()}) for '${cli.name}'.`));
+        if (cli.homepage)
+            console.error(`See: ${cli.homepage}`);
+        return false;
+    }
+    console.log(chalk.cyan(`🔹 '${cli.name}' is not installed. Auto-installing...`));
+    console.log(chalk.dim(`$ ${cmd}`));
+    try {
+        execSync(cmd, { stdio: 'inherit' });
+        console.log(chalk.green(`✅ Installed '${cli.name}' successfully.\n`));
+        return true;
+    }
+    catch (err) {
+        console.error(chalk.red(`❌ Failed to install '${cli.name}': ${err.message}`));
+        return false;
+    }
+}
+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.`);
+    }
+    // 1. Check if installed
+    if (!isBinaryInstalled(cli.binary)) {
+        // 2. Try to auto install
+        const success = installExternalCli(cli);
+        if (!success) {
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 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}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (result.status !== null) {
+        process.exitCode = result.status;
+    }
+}
+export function registerExternalCli(name, opts) {
+    const userPath = getUserRegistryPath();
+    const configDir = path.dirname(userPath);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    let items = [];
+    if (fs.existsSync(userPath)) {
+        try {
+            const raw = fs.readFileSync(userPath, 'utf8');
+            items = (yaml.load(raw) || []);
+        }
+        catch {
+            // Ignore
+        }
+    }
+    const existingIndex = items.findIndex((c) => c.name === name);
+    const newItem = {
+        name,
+        binary: opts?.binary || name,
+    };
+    if (opts?.description)
+        newItem.description = opts.description;
+    if (opts?.install)
+        newItem.install = { default: opts.install };
+    if (existingIndex >= 0) {
+        items[existingIndex] = { ...items[existingIndex], ...newItem };
+        console.log(chalk.green(`Updated '${name}' in user registry.`));
+    }
+    else {
+        items.push(newItem);
+        console.log(chalk.green(`Registered '${name}' in user registry.`));
+    }
+    const dump = yaml.dump(items, { indent: 2, sortKeys: true });
+    fs.writeFileSync(userPath, dump, 'utf8');
+    console.log(chalk.dim(userPath));
+}

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;