@jackwener/opencli 1.0.6 → 1.1.1

package/src/explore.ts

@@ -223,6 +223,132 @@ export interface DiscoveredStore {
 
 const INTERACT_FUZZ_JS = interactFuzz.toString();
 
+// ── Analysis helpers (extracted from exploreUrl) ───────────────────────────
+
+/** Filter, deduplicate, and score network endpoints. */
+function analyzeEndpoints(networkEntries: NetworkEntry[]): { analyzed: AnalyzedEndpoint[]; totalCount: number } {
+  const seen = new Map<string, AnalyzedEndpoint>();
+  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: string[] = [];
+    try { new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k)) qp.push(k); }); } catch {}
+
+    const ep: AnalyzedEndpoint = {
+      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: AnalyzedEndpoint[],
+  stores: DiscoveredStore[],
+  opts: { site?: string; goal?: string; url: string },
+): { capabilities: InferredCapability[]; topStrategy: string; authIndicators: string[] } {
+  const capabilities: InferredCapability[] = [];
+  const usedNames = new Set<string>();
+
+  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: string[] = [];
+    if (ep.responseAnalysis) {
+      for (const role of ['title', 'url', 'author', 'score', 'time']) {
+        if (ep.responseAnalysis.detectedFields[role]) cols.push(role);
+      }
+    }
+
+    const args: InferredCapability['recommendedArgs'] = [];
+    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: { store: string; action: string } | undefined;
+    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: string,
+  result: Record<string, any>,
+  analyzedEndpoints: AnalyzedEndpoint[],
+  stores: DiscoveredStore[],
+): Promise<void> {
+  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(
@@ -317,125 +443,25 @@ export async function exploreUrl(
         } catch {}
       }
 
-      // Step 7: Analyze endpoints
-      const seen = new Map<string, AnalyzedEndpoint>();
-      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: string[] = [];
-        try { new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k)) qp.push(k); }); } catch {}
-
-        const ep: AnalyzedEndpoint = {
-          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: InferredCapability[] = [];
-      const usedNames = new Set<string>();
-      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: string[] = [];
-        if (ep.responseAnalysis) {
-          for (const role of ['title', 'url', 'author', 'score', 'time']) {
-            if (ep.responseAnalysis.detectedFields[role]) cols.push(role);
-          }
-        }
-
-        const args: InferredCapability['recommendedArgs'] = [];
-        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: { store: string; action: string } | undefined;
-        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/src/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/src/external.ts

@@ -0,0 +1,185 @@
+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));
+
+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;
+}
+
+function getUserRegistryPath(): string {
+  const home = os.homedir();
+  return path.join(home, '.opencli', 'external-clis.yaml');
+}
+
+export function loadExternalClis(): ExternalCliConfig[] {
+  const configs = new Map<string, ExternalCliConfig>();
+
+  // 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) || []) as ExternalCliConfig[];
+      for (const item of parsed) configs.set(item.name, item);
+    }
+  } catch (err: any) {
+    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) || []) as ExternalCliConfig[];
+      for (const item of parsed) {
+        configs.set(item.name, item); // Overwrite built-in if duplicated
+      }
+    }
+  } catch (err: any) {
+    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: string): boolean {
+  try {
+    const isWindows = os.platform() === 'win32';
+    execFileSync(isWindows ? 'where' : 'which', [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getInstallCmd(installConfig?: ExternalCliInstall): string | null {
+  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: ExternalCliConfig): boolean {
+  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: any) {
+    console.error(chalk.red(`❌ Failed to install '${cli.name}': ${err.message}`));
+    return false;
+  }
+}
+
+export function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void {
+  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 interface RegisterOptions {
+  binary?: string;
+  install?: string;
+  description?: string;
+}
+
+export function registerExternalCli(name: string, opts?: RegisterOptions): void {
+  const userPath = getUserRegistryPath();
+  const configDir = path.dirname(userPath);
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  let items: ExternalCliConfig[] = [];
+  if (fs.existsSync(userPath)) {
+    try {
+      const raw = fs.readFileSync(userPath, 'utf8');
+      items = (yaml.load(raw) || []) as ExternalCliConfig[];
+    } catch {
+      // Ignore
+    }
+  }
+
+  const existingIndex = items.findIndex((c) => c.name === name);
+  
+  const newItem: ExternalCliConfig = {
+    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/src/main.ts

@@ -6,7 +6,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';
 

package/src/pipeline/steps/browser.ts

@@ -7,8 +7,13 @@ import type { IPage } from '../../types.js';
 import { render } from '../template.js';
 
 export async function stepNavigate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
-  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;
 }
 

package/src/registry.ts

@@ -89,3 +89,8 @@ export function strategyLabel(cmd: CliCommand): string {
 export function registerCommand(cmd: CliCommand): void {
   _registry.set(fullName(cmd), cmd);
 }
+
+// Re-export serialization helpers from their dedicated module
+export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';
+export type { SerializedArg } from './serialization.js';
+

package/src/runtime.ts

@@ -1,5 +1,14 @@
+import { BrowserBridge, CDPBridge } from './browser/index.js';
 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 function getBrowserFactory(): new () => IBrowserFactory {
+  return (process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge) as any;
+}
+
 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/src/serialization.ts

@@ -0,0 +1,79 @@
+/**
+ * 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';
+import { fullName, strategyLabel } from './registry.js';
+
+// ── Serialization ───────────────────────────────────────────────────────────
+
+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 function serializeArg(a: Arg): SerializedArg {
+  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: CliCommand) {
+  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: Arg[]): string {
+  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: CliCommand): string {
+  const lines: string[] = [];
+  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: string[] = [];
+  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/src/types.ts

@@ -6,7 +6,7 @@
  */
 
 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; url?: string }): Promise<Array<{
     name: string;

package/tests/e2e/browser-public.test.ts

@@ -46,6 +46,31 @@ describe('browser public-data commands E2E', () => {
     }
   }, 60_000);
 
+  it('bloomberg news returns article detail when the article page is accessible', async () => {
+    const feedResult = await runCli(['bloomberg', 'tech', '--limit', '1', '-f', 'json']);
+    if (feedResult.code !== 0) {
+      console.warn('bloomberg news: skipped — could not load Bloomberg tech feed');
+      return;
+    }
+
+    const feedItems = parseJsonOutput(feedResult.stdout);
+    const link = Array.isArray(feedItems) ? feedItems[0]?.link : null;
+    if (!link) {
+      console.warn('bloomberg news: skipped — tech feed returned no link');
+      return;
+    }
+
+    const data = await tryBrowserCommand(['bloomberg', 'news', link, '-f', 'json']);
+    expectDataOrSkip(data, 'bloomberg news');
+    if (data) {
+      expect(data[0]).toHaveProperty('title');
+      expect(data[0]).toHaveProperty('summary');
+      expect(data[0]).toHaveProperty('link');
+      expect(data[0]).toHaveProperty('mediaLinks');
+      expect(data[0]).toHaveProperty('content');
+    }
+  }, 60_000);
+
   // ── v2ex daily (browser: true) ──
   it('v2ex daily returns topics', async () => {
     const data = await tryBrowserCommand(['v2ex', 'daily', '--limit', '3', '-f', 'json']);