@jackwener/opencli 1.1.0 → 1.2.0

package/src/cli.ts

@@ -1,57 +1,91 @@
+/**
+ * CLI entry point: registers built-in commands and wires up Commander.
+ *
+ * Built-in commands are registered inline here (list, validate, explore, etc.).
+ * Dynamic adapter commands are registered via commanderAdapter.ts.
+ */
+
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { executeCommand } from './engine.js';
-import { Strategy, type CliCommand, fullName, getRegistry, strategyLabel } from './registry.js';
+import { type CliCommand, fullName, getRegistry, strategyLabel } from './registry.js';
+import { serializeCommand, formatArgSummary } from './serialization.js';
 import { render as renderOutput } from './output.js';
-import { BrowserBridge, CDPBridge } from './browser/index.js';
-import { browserSession, DEFAULT_BROWSER_COMMAND_TIMEOUT, runWithTimeout } from './runtime.js';
+import { getBrowserFactory, browserSession } from './runtime.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
-import { CliError } from './errors.js';
-import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
+import { registerAllCommands } from './commanderAdapter.js';
 
 export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
   const program = new Command();
-  program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version(PKG_VERSION);
+  // enablePositionalOptions: prevents parent from consuming flags meant for subcommands;
+  // prerequisite for passThroughOptions to forward --help/--version to external binaries
+  program
+    .name('opencli')
+    .description('Make any website your CLI. Zero setup. AI-powered.')
+    .version(PKG_VERSION)
+    .enablePositionalOptions();
 
-  // ── Built-in commands ──────────────────────────────────────────────────────
+  // ── Built-in: list ────────────────────────────────────────────────────────
 
-  program.command('list').description('List all available CLI commands').option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table').option('--json', 'JSON output (deprecated)')
+  program
+    .command('list')
+    .description('List all available CLI commands')
+    .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
+    .option('--json', 'JSON output (deprecated)')
     .action((opts) => {
       const registry = getRegistry();
       const commands = [...registry.values()].sort((a, b) => fullName(a).localeCompare(fullName(b)));
-      const rows = commands.map(c => ({
-        command: fullName(c),
-        site: c.site,
-        name: c.name,
-        description: c.description,
-        strategy: strategyLabel(c),
-        browser: c.browser,
-        args: c.args.map(a => a.name).join(', '),
-      }));
       const fmt = opts.json && opts.format === 'table' ? 'json' : opts.format;
+      const isStructured = fmt === 'json' || fmt === 'yaml';
+
       if (fmt !== 'table') {
+        const rows = isStructured
+          ? commands.map(serializeCommand)
+          : commands.map(c => ({
+              command: fullName(c),
+              site: c.site,
+              name: c.name,
+              description: c.description,
+              strategy: strategyLabel(c),
+              browser: !!c.browser,
+              args: formatArgSummary(c.args),
+            }));
         renderOutput(rows, {
           fmt,
-          columns: ['command', 'site', 'name', 'description', 'strategy', 'browser', 'args'],
+          columns: ['command', 'site', 'name', 'description', 'strategy', 'browser', 'args',
+                     ...(isStructured ? ['columns', 'domain'] : [])],
           title: 'opencli/list',
           source: 'opencli list',
         });
         return;
       }
+
+      // Table (default) — grouped by site
       const sites = new Map<string, CliCommand[]>();
-      for (const cmd of commands) { const g = sites.get(cmd.site) ?? []; g.push(cmd); sites.set(cmd.site, g); }
-      console.log(); console.log(chalk.bold('  opencli') + chalk.dim(' — available commands')); console.log();
+      for (const cmd of commands) {
+        const g = sites.get(cmd.site) ?? [];
+        g.push(cmd);
+        sites.set(cmd.site, g);
+      }
+
+      console.log();
+      console.log(chalk.bold('  opencli') + chalk.dim(' — available commands'));
+      console.log();
       for (const [site, cmds] of sites) {
         console.log(chalk.bold.cyan(`  ${site}`));
-        for (const cmd of cmds) { const tag = strategyLabel(cmd) === 'public' ? chalk.green('[public]') : chalk.yellow(`[${strategyLabel(cmd)}]`); console.log(`    ${cmd.name} ${tag}${cmd.description ? chalk.dim(` — ${cmd.description}`) : ''}`); }
+        for (const cmd of cmds) {
+          const tag = strategyLabel(cmd) === 'public'
+            ? chalk.green('[public]')
+            : chalk.yellow(`[${strategyLabel(cmd)}]`);
+          console.log(`    ${cmd.name} ${tag}${cmd.description ? chalk.dim(` — ${cmd.description}`) : ''}`);
+        }
         console.log();
       }
-      
+
       const externalClis = loadExternalClis();
       if (externalClis.length > 0) {
-        console.log(chalk.bold.cyan(`  external CLIs`));
+        console.log(chalk.bold.cyan('  external CLIs'));
         for (const ext of externalClis) {
           const isInstalled = isBinaryInstalled(ext.binary);
           const tag = isInstalled ? chalk.green('[installed]') : chalk.yellow('[auto-install]');
@@ -59,17 +93,27 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
         }
         console.log();
       }
-      
-      console.log(chalk.dim(`  ${commands.length} built-in commands across ${sites.size} sites, ${externalClis.length} external CLIs`)); console.log();
+
+      console.log(chalk.dim(`  ${commands.length} built-in commands across ${sites.size} sites, ${externalClis.length} external CLIs`));
+      console.log();
     });
 
-  program.command('validate').description('Validate CLI definitions').argument('[target]', 'site or site/name')
+  // ── Built-in: validate / verify ───────────────────────────────────────────
+
+  program
+    .command('validate')
+    .description('Validate CLI definitions')
+    .argument('[target]', 'site or site/name')
     .action(async (target) => {
       const { validateClisWithTarget, renderValidationReport } = await import('./validate.js');
       console.log(renderValidationReport(validateClisWithTarget([BUILTIN_CLIS, USER_CLIS], target)));
     });
 
-  program.command('verify').description('Validate + smoke test').argument('[target]').option('--smoke', 'Run smoke tests', false)
+  program
+    .command('verify')
+    .description('Validate + smoke test')
+    .argument('[target]')
+    .option('--smoke', 'Run smoke tests', false)
     .action(async (target, opts) => {
       const { verifyClis, renderVerifyReport } = await import('./verify.js');
       const r = await verifyClis({ builtinClis: BUILTIN_CLIS, userClis: USER_CLIS, target, smoke: opts.smoke });
@@ -77,28 +121,91 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       process.exitCode = r.ok ? 0 : 1;
     });
 
-  program.command('explore').alias('probe').description('Explore a website: discover APIs, stores, and recommend strategies').argument('<url>').option('--site <name>').option('--goal <text>').option('--wait <s>', '', '3').option('--auto', 'Enable interactive fuzzing (simulate clicks to trigger lazy APIs)').option('--click <labels>', 'Comma-separated labels to click before fuzzing (e.g. "字幕,CC,评论")')
-    .action(async (url, opts) => { const { exploreUrl, renderExploreSummary } = await import('./explore.js'); const clickLabels = opts.click ? opts.click.split(',').map((s: string) => s.trim()) : undefined; const BrowserFactory = process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge; const workspace = `explore:${opts.site ?? (() => { try { return new URL(url).host; } catch { return 'default'; } })()}`; console.log(renderExploreSummary(await exploreUrl(url, { BrowserFactory: BrowserFactory as any, site: opts.site, goal: opts.goal, waitSeconds: parseFloat(opts.wait), auto: opts.auto, clickLabels, workspace }))); });
+  // ── Built-in: explore / synthesize / generate / cascade ───────────────────
 
-  program.command('synthesize').description('Synthesize CLIs from explore').argument('<target>').option('--top <n>', '', '3')
-    .action(async (target, opts) => { const { synthesizeFromExplore, renderSynthesizeSummary } = await import('./synthesize.js'); console.log(renderSynthesizeSummary(synthesizeFromExplore(target, { top: parseInt(opts.top) }))); });
+  program
+    .command('explore')
+    .alias('probe')
+    .description('Explore a website: discover APIs, stores, and recommend strategies')
+    .argument('<url>')
+    .option('--site <name>')
+    .option('--goal <text>')
+    .option('--wait <s>', '', '3')
+    .option('--auto', 'Enable interactive fuzzing')
+    .option('--click <labels>', 'Comma-separated labels to click before fuzzing')
+    .action(async (url, opts) => {
+      const { exploreUrl, renderExploreSummary } = await import('./explore.js');
+      const clickLabels = opts.click
+        ? opts.click.split(',').map((s: string) => s.trim())
+        : undefined;
+      const workspace = `explore:${inferHost(url, opts.site)}`;
+      const result = await exploreUrl(url, {
+        BrowserFactory: getBrowserFactory(),
+        site: opts.site,
+        goal: opts.goal,
+        waitSeconds: parseFloat(opts.wait),
+        auto: opts.auto,
+        clickLabels,
+        workspace,
+      });
+      console.log(renderExploreSummary(result));
+    });
 
-  program.command('generate').description('One-shot: explore → synthesize → register').argument('<url>').option('--goal <text>').option('--site <name>')
-    .action(async (url, opts) => { const { generateCliFromUrl, renderGenerateSummary } = await import('./generate.js'); const BrowserFactory = process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge; const workspace = `generate:${opts.site ?? (() => { try { return new URL(url).host; } catch { return 'default'; } })()}`; const r = await generateCliFromUrl({ url, BrowserFactory: BrowserFactory as any, builtinClis: BUILTIN_CLIS, userClis: USER_CLIS, goal: opts.goal, site: opts.site, workspace }); console.log(renderGenerateSummary(r)); process.exitCode = r.ok ? 0 : 1; });
+  program
+    .command('synthesize')
+    .description('Synthesize CLIs from explore')
+    .argument('<target>')
+    .option('--top <n>', '', '3')
+    .action(async (target, opts) => {
+      const { synthesizeFromExplore, renderSynthesizeSummary } = await import('./synthesize.js');
+      console.log(renderSynthesizeSummary(synthesizeFromExplore(target, { top: parseInt(opts.top) })));
+    });
 
-  program.command('cascade').description('Strategy cascade: find simplest working strategy').argument('<url>').option('--site <name>')
+  program
+    .command('generate')
+    .description('One-shot: explore → synthesize → register')
+    .argument('<url>')
+    .option('--goal <text>')
+    .option('--site <name>')
+    .action(async (url, opts) => {
+      const { generateCliFromUrl, renderGenerateSummary } = await import('./generate.js');
+      const workspace = `generate:${inferHost(url, opts.site)}`;
+      const r = await generateCliFromUrl({
+        url,
+        BrowserFactory: getBrowserFactory(),
+        builtinClis: BUILTIN_CLIS,
+        userClis: USER_CLIS,
+        goal: opts.goal,
+        site: opts.site,
+        workspace,
+      });
+      console.log(renderGenerateSummary(r));
+      process.exitCode = r.ok ? 0 : 1;
+    });
+
+  program
+    .command('cascade')
+    .description('Strategy cascade: find simplest working strategy')
+    .argument('<url>')
+    .option('--site <name>')
     .action(async (url, opts) => {
       const { cascadeProbe, renderCascadeResult } = await import('./cascade.js');
-      const BrowserFactory = process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge;
-      const result = await browserSession(BrowserFactory as any, async (page) => {
-        // Navigate to the site first for cookie context
-        try { const siteUrl = new URL(url); await page.goto(`${siteUrl.protocol}//${siteUrl.host}`); await page.wait(2); } catch {}
+      const workspace = `cascade:${inferHost(url, opts.site)}`;
+      const result = await browserSession(getBrowserFactory(), async (page) => {
+        try {
+          const siteUrl = new URL(url);
+          await page.goto(`${siteUrl.protocol}//${siteUrl.host}`);
+          await page.wait(2);
+        } catch {}
         return cascadeProbe(page, url);
-      }, { workspace: `cascade:${opts.site ?? (() => { try { return new URL(url).host; } catch { return 'default'; } })()}` });
+      }, { workspace });
       console.log(renderCascadeResult(result));
     });
 
-  program.command('doctor')
+  // ── Built-in: doctor / setup / completion ─────────────────────────────────
+
+  program
+    .command('doctor')
     .description('Diagnose opencli browser bridge connectivity')
     .option('--live', 'Test browser connectivity (requires Chrome running)', false)
     .option('--sessions', 'Show active automation sessions', false)
@@ -108,66 +215,150 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       console.log(renderBrowserDoctorReport(report));
     });
 
-  program.command('setup')
+  program
+    .command('setup')
     .description('Interactive setup: verify browser bridge connectivity')
     .action(async () => {
       const { runSetup } = await import('./setup.js');
       await runSetup({ cliVersion: PKG_VERSION });
     });
 
-  program.command('completion')
+  program
+    .command('completion')
     .description('Output shell completion script')
     .argument('<shell>', 'Shell type: bash, zsh, or fish')
     .action((shell) => {
       printCompletionScript(shell);
     });
 
+  // ── Plugin management ──────────────────────────────────────────────────────
+
+  const pluginCmd = program.command('plugin').description('Manage opencli plugins');
+
+  pluginCmd
+    .command('install')
+    .description('Install a plugin from GitHub')
+    .argument('<source>', 'Plugin source (e.g. github:user/repo)')
+    .action(async (source: string) => {
+      const { installPlugin } = await import('./plugin.js');
+      try {
+        const name = installPlugin(source);
+        console.log(chalk.green(`✅ Plugin "${name}" installed successfully.`));
+        console.log(chalk.dim(`   Restart opencli to use the new commands.`));
+      } catch (err: any) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  pluginCmd
+    .command('uninstall')
+    .description('Uninstall a plugin')
+    .argument('<name>', 'Plugin name')
+    .action(async (name: string) => {
+      const { uninstallPlugin } = await import('./plugin.js');
+      try {
+        uninstallPlugin(name);
+        console.log(chalk.green(`✅ Plugin "${name}" uninstalled.`));
+      } catch (err: any) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  pluginCmd
+    .command('list')
+    .description('List installed plugins')
+    .option('-f, --format <fmt>', 'Output format: table, json', 'table')
+    .action(async (opts) => {
+      const { listPlugins } = await import('./plugin.js');
+      const plugins = listPlugins();
+      if (plugins.length === 0) {
+        console.log(chalk.dim('  No plugins installed.'));
+        console.log(chalk.dim(`  Install one with: opencli plugin install github:user/repo`));
+        return;
+      }
+      if (opts.format === 'json') {
+        renderOutput(plugins, {
+          fmt: 'json',
+          columns: ['name', 'commands', 'source'],
+          title: 'opencli/plugins',
+          source: 'opencli plugin list',
+        });
+        return;
+      }
+      console.log();
+      console.log(chalk.bold('  Installed plugins'));
+      console.log();
+      for (const p of plugins) {
+        const cmds = p.commands.length > 0 ? chalk.dim(` (${p.commands.join(', ')})`) : '';
+        const src = p.source ? chalk.dim(` ← ${p.source}`) : '';
+        console.log(`  ${chalk.cyan(p.name)}${cmds}${src}`);
+      }
+      console.log();
+      console.log(chalk.dim(`  ${plugins.length} plugin(s) installed`));
+      console.log();
+    });
+
+  // ── External CLIs ─────────────────────────────────────────────────────────
+
   const externalClis = loadExternalClis();
 
-  program.command('install')
+  program
+    .command('install')
     .description('Install an external CLI')
     .argument('<name>', 'Name of the external CLI')
     .action((name: string) => {
       const ext = externalClis.find(e => e.name === name);
       if (!ext) {
-         console.error(chalk.red(`External CLI '${name}' not found in registry.`));
-         process.exitCode = 1;
-         return;
+        console.error(chalk.red(`External CLI '${name}' not found in registry.`));
+        process.exitCode = 1;
+        return;
       }
       installExternalCli(ext);
     });
 
-  program.command('register')
+  program
+    .command('register')
     .description('Register an external CLI')
     .argument('<name>', 'Name of the CLI')
     .option('--binary <bin>', 'Binary name if different from name')
     .option('--install <cmd>', 'Auto-install command')
     .option('--desc <text>', 'Description')
     .action((name, opts) => {
-      registerExternalCli(name, opts.binary, opts.install, opts.desc);
+      registerExternalCli(name, { binary: opts.binary, install: opts.install, description: opts.desc });
     });
 
+  function passthroughExternal(name: string, parsedArgs?: string[]) {
+    const args = parsedArgs ?? (() => {
+      const idx = process.argv.indexOf(name);
+      return process.argv.slice(idx + 1);
+    })();
+    try {
+      executeExternalCli(name, args, externalClis);
+    } catch (err: any) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exitCode = 1;
+    }
+  }
+
   for (const ext of externalClis) {
     if (program.commands.some(c => c.name() === ext.name)) continue;
-    program.command(ext.name)
+    program
+      .command(ext.name)
       .description(`(External) ${ext.description || ext.name}`)
+      .argument('[args...]')
       .allowUnknownOption()
-      .action(() => {
-        // Retrieve args passed to the external CLI
-        // Commander consumes standard args before the action, so we must slice process.argv directly.
-        const extIndex = process.argv.indexOf(ext.name);
-        const args = process.argv.slice(extIndex + 1);
-        executeExternalCli(ext.name, args).catch(err => {
-          console.error(chalk.red(`Error: ${err.message}`));
-          process.exitCode = 1;
-        });
-      });
+      .passThroughOptions()
+      .helpOption(false)
+      .action((args: string[]) => passthroughExternal(ext.name, args));
   }
 
-  // ── Antigravity serve (built-in, long-running) ──────────────────────────────
+  // ── Antigravity serve (long-running, special case) ────────────────────────
 
   const antigravityCmd = program.command('antigravity').description('antigravity commands');
-  antigravityCmd.command('serve')
+  antigravityCmd
+    .command('serve')
     .description('Start Anthropic-compatible API proxy for Antigravity')
     .option('--port <port>', 'Server port (default: 8082)', '8082')
     .action(async (opts) => {
@@ -175,88 +366,45 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       await startServe({ port: parseInt(opts.port) });
     });
 
-  // ── Dynamic site commands ──────────────────────────────────────────────────
+  // ── Dynamic adapter commands ──────────────────────────────────────────────
 
-  const registry = getRegistry();
   const siteGroups = new Map<string, Command>();
-  // Pre-seed with the antigravity command registered above to avoid duplicates
   siteGroups.set('antigravity', antigravityCmd);
+  registerAllCommands(program, siteGroups);
 
-  for (const [, cmd] of registry) {
-    let siteCmd = siteGroups.get(cmd.site);
-    if (!siteCmd) { siteCmd = program.command(cmd.site).description(`${cmd.site} commands`); siteGroups.set(cmd.site, siteCmd); }
-    // Skip if this subcommand was already hardcoded (e.g. antigravity serve)
-    if (siteCmd.commands.some((c: Command) => c.name() === cmd.name)) continue;
-    const subCmd = siteCmd.command(cmd.name).description(cmd.description);
-
-    // Register positional args first, then named options
-    const positionalArgs: typeof cmd.args = [];
-    for (const arg of cmd.args) {
-      if (arg.positional) {
-        const bracket = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
-        subCmd.argument(bracket, arg.help ?? '');
-        positionalArgs.push(arg);
-      } else {
-        const flag = arg.required ? `--${arg.name} <value>` : `--${arg.name} [value]`;
-        if (arg.required) subCmd.requiredOption(flag, arg.help ?? '');
-        else if (arg.default != null) subCmd.option(flag, arg.help ?? '', String(arg.default));
-        else subCmd.option(flag, arg.help ?? '');
-      }
-    }
-    subCmd.option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table').option('-v, --verbose', 'Debug output', false);
-
-    subCmd.action(async (...actionArgs: any[]) => {
-      // Commander passes positional args first, then options object, then the Command
-      const actionOpts = actionArgs[positionalArgs.length] ?? {};
-      const startTime = Date.now();
-      const kwargs: Record<string, any> = {};
-      
-      // Collect positional args
-      for (let i = 0; i < positionalArgs.length; i++) {
-        const arg = positionalArgs[i];
-        const v = actionArgs[i];
-        if (v !== undefined) kwargs[arg.name] = v;
-      }
-      
-      // Collect named options
-      for (const arg of cmd.args) {
-        if (arg.positional) continue;
-        const camelName = arg.name.replace(/-([a-z])/g, (_m, ch: string) => ch.toUpperCase());
-        const v = actionOpts[arg.name] ?? actionOpts[camelName];
-        if (v !== undefined) kwargs[arg.name] = v;
-      }
+  // ── Unknown command fallback ──────────────────────────────────────────────
 
-      try {
-        if (actionOpts.verbose) process.env.OPENCLI_VERBOSE = '1';
-        let result: any;
-        if (shouldUseBrowserSession(cmd)) {
-          const BrowserFactory = process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge;
-          result = await browserSession(BrowserFactory as any, 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(executeCommand(cmd, page, kwargs, actionOpts.verbose), { timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT, label: fullName(cmd) });
-          }, { workspace: `site:${cmd.site}` });
-        } else { result = await executeCommand(cmd, null, kwargs, actionOpts.verbose); }
-        if (actionOpts.verbose && (!result || (Array.isArray(result) && result.length === 0))) {
-          console.error(chalk.yellow(`[Verbose] Warning: Command returned an empty result. If the website structural API changed or requires authentication, check the network or update the adapter.`));
-        }
-        const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
-        renderOutput(result, { fmt: actionOpts.format, columns: resolved.columns, title: `${resolved.site}/${resolved.name}`, elapsed: (Date.now() - startTime) / 1000, source: fullName(resolved), footerExtra: resolved.footerExtra?.(kwargs) });
-      } catch (err: any) { 
-        if (err instanceof CliError) {
-          console.error(chalk.red(`Error [${err.code}]: ${err.message}`));
-          if (err.hint) console.error(chalk.yellow(`Hint: ${err.hint}`));
-        } else if (actionOpts.verbose && err.stack) {
-          console.error(chalk.red(err.stack));
-        } else {
-          console.error(chalk.red(`Error: ${err.message ?? err}`));
-        }
-        process.exitCode = 1; 
-      }
-    });
-  }
+  const DENY_LIST = new Set([
+    'rm', 'sudo', 'dd', 'mkfs', 'fdisk', 'shutdown', 'reboot',
+    'kill', 'killall', 'chmod', 'chown', 'passwd', 'su', 'mount',
+    'umount', 'format', 'diskutil',
+  ]);
+
+  program.on('command:*', (operands: string[]) => {
+    const binary = operands[0];
+    if (DENY_LIST.has(binary)) {
+      console.error(chalk.red(`Refusing to register system command '${binary}'.`));
+      process.exitCode = 1;
+      return;
+    }
+    if (isBinaryInstalled(binary)) {
+      console.log(chalk.cyan(`🔹 Auto-discovered local CLI '${binary}'. Registering...`));
+      registerExternalCli(binary);
+      passthroughExternal(binary);
+    } else {
+      console.error(chalk.red(`error: unknown command '${binary}'`));
+      program.outputHelp();
+      process.exitCode = 1;
+    }
+  });
 
   program.parse();
 }
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Infer a workspace-friendly hostname from a URL, with site override. */
+function inferHost(url: string, site?: string): string {
+  if (site) return site;
+  try { return new URL(url).host; } catch { return 'default'; }
+}

package/src/clis/apple-podcasts/commands.test.ts

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '../../registry.js';
+import './search.js';
+import './top.js';
+
+describe('apple-podcasts search command', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('uses the positional query argument for the iTunes search request', async () => {
+    const cmd = getRegistry().get('apple-podcasts/search');
+    expect(cmd?.func).toBeTypeOf('function');
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        results: [
+          {
+            collectionId: 42,
+            collectionName: 'Machine Learning Guide',
+            artistName: 'OpenCLI',
+            trackCount: 12,
+            primaryGenreName: 'Technology',
+          },
+        ],
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await cmd!.func!(null as any, {
+      query: 'machine learning',
+      keyword: 'sports',
+      limit: 5,
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://itunes.apple.com/search?term=machine%20learning&media=podcast&limit=5',
+    );
+    expect(result).toEqual([
+      {
+        id: 42,
+        title: 'Machine Learning Guide',
+        author: 'OpenCLI',
+        episodes: 12,
+        genre: 'Technology',
+      },
+    ]);
+  });
+});
+
+describe('apple-podcasts top command', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('uses the canonical Apple charts host and maps ranked results', async () => {
+    const cmd = getRegistry().get('apple-podcasts/top');
+    expect(cmd?.func).toBeTypeOf('function');
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        feed: {
+          results: [
+            { id: '100', name: 'Top Show', artistName: 'Host A' },
+            { id: '101', name: 'Second Show', artistName: 'Host B' },
+          ],
+        },
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await cmd!.func!(null as any, { country: 'US', limit: 2 });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://rss.marketingtools.apple.com/api/v2/us/podcasts/top/2/podcasts.json',
+    );
+    expect(result).toEqual([
+      { rank: 1, title: 'Top Show', author: 'Host A', id: '100' },
+      { rank: 2, title: 'Second Show', author: 'Host B', id: '101' },
+    ]);
+  });
+
+  it('normalizes network failures into CliError output', async () => {
+    const cmd = getRegistry().get('apple-podcasts/top');
+    expect(cmd?.func).toBeTypeOf('function');
+
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('socket hang up')));
+
+    await expect(cmd!.func!(null as any, { country: 'us', limit: 3 })).rejects.toThrow(
+      'Unable to reach Apple Podcasts charts for US',
+    );
+  });
+});

package/src/clis/apple-podcasts/search.ts

@@ -9,12 +9,12 @@ cli({
   strategy: Strategy.PUBLIC,
   browser: false,
   args: [
-    { name: 'keyword', positional: true, required: true, help: 'Search keyword' },
+    { name: 'query', positional: true, required: true, help: 'Search keyword' },
     { name: 'limit', type: 'int', default: 10, help: 'Max results' },
   ],
   columns: ['id', 'title', 'author', 'episodes', 'genre'],
   func: async (_page, args) => {
-    const term = encodeURIComponent(args.keyword);
+    const term = encodeURIComponent(args.query);
     const limit = Math.max(1, Math.min(Number(args.limit), 25));
     const data = await itunesFetch(`/search?term=${term}&media=podcast&limit=${limit}`);
     if (!data.results?.length) throw new CliError('NOT_FOUND', 'No podcasts found', `Try a different keyword`);