@jackwener/opencli 1.1.0 → 1.2.0

package/src/clis/xiaohongshu/download.ts

@@ -22,17 +22,16 @@ cli({
   domain: 'www.xiaohongshu.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'note_id', required: true, help: 'Note ID (from URL)' },
+    { name: 'note-id', positional: true, required: true, help: 'Note ID (from URL)' },
     { name: 'output', default: './xiaohongshu-downloads', help: 'Output directory' },
   ],
   columns: ['index', 'type', 'status', 'size'],
   func: async (page, kwargs) => {
-    const noteId = kwargs.note_id;
+    const noteId = kwargs['note-id'];
     const output = kwargs.output;
 
     // Navigate to note page
     await page.goto(`https://www.xiaohongshu.com/explore/${noteId}`);
-    await page.wait(3);
 
     // Extract note info and media URLs
     const data = await page.evaluate(`

package/src/clis/xiaohongshu/feed.yaml

@@ -15,7 +15,6 @@ columns: [title, author, likes, type, url]
 
 pipeline:
   - navigate: https://www.xiaohongshu.com/explore
-  - wait: 3
   - tap:
       store: feed
       action: fetchFeeds

package/src/clis/xiaohongshu/notifications.yaml

@@ -19,7 +19,6 @@ columns: [rank, user, action, content, note, time]
 
 pipeline:
   - navigate: https://www.xiaohongshu.com/notification
-  - wait: 3
   - tap:
       store: notification
       action: getNotification

package/src/clis/xiaohongshu/search.ts

@@ -15,12 +15,12 @@ cli({
   domain: 'www.xiaohongshu.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'keyword', required: true, help: 'Search keyword' },
+    { name: 'query', required: true, positional: true, help: 'Search keyword' },
     { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
   ],
   columns: ['rank', 'title', 'author', 'likes'],
   func: async (page, kwargs) => {
-    const keyword = encodeURIComponent(kwargs.keyword);
+    const keyword = encodeURIComponent(kwargs.query);
     await page.goto(
       `https://www.xiaohongshu.com/search_result?keyword=${keyword}&source=web_search_result_notes`
     );

package/src/clis/xiaohongshu/user.ts

@@ -29,7 +29,7 @@ cli({
   strategy: Strategy.COOKIE,
   browser: true,
   args: [
-    { name: 'id', type: 'string', required: true, help: 'User id or profile URL' },
+    { name: 'id', type: 'string', required: true, positional: true, help: 'User id or profile URL' },
     { name: 'limit', type: 'int', default: 15, help: 'Number of notes to return' },
   ],
   columns: ['id', 'title', 'type', 'likes', 'url'],
@@ -38,7 +38,6 @@ cli({
     const limit = Math.max(1, Number(kwargs.limit ?? 15));
 
     await page.goto(`https://www.xiaohongshu.com/user/profile/${userId}`);
-    await page.wait(3);
 
     let snapshot = await readUserSnapshot(page);
     let results = extractXhsUserNotes(snapshot ?? {}, userId);

package/src/clis/xueqiu/earnings-date.yaml

@@ -0,0 +1,69 @@
+site: xueqiu
+name: earnings-date
+description: 获取股票预计财报发布日期（公司大事）
+domain: xueqiu.com
+browser: true
+
+args:
+  symbol:
+    positional: true
+    type: str
+    required: true
+    description: 股票代码，如 SH600519、SZ000858、00700
+  next:
+    type: bool
+    default: false
+    description: 仅返回最近一次未发布的财报日期
+  limit:
+    type: int
+    default: 10
+    description: 返回数量，默认 10
+
+pipeline:
+  - navigate: https://xueqiu.com
+  - evaluate: |
+      (async () => {
+        const symbol = (${{ args.symbol | json }} || '').toUpperCase();
+        const onlyNext = ${{ args.next }};
+        if (!symbol) throw new Error('Missing argument: symbol');
+        const resp = await fetch(
+          `https://stock.xueqiu.com/v5/stock/screener/event/list.json?symbol=${encodeURIComponent(symbol)}&page=1&size=100`,
+          { credentials: 'include' }
+        );
+        if (!resp.ok) throw new Error('HTTP ' + resp.status + ' Hint: Not logged in?');
+        const d = await resp.json();
+        if (!d.data || !d.data.items) throw new Error('获取失败: ' + JSON.stringify(d));
+
+        // subtype 2 = 预计财报发布
+        let items = d.data.items.filter(item => item.subtype === 2);
+
+        const now = Date.now();
+        let results = items.map(item => {
+          const ts = item.timestamp;
+          const dateStr = ts ? new Date(ts).toISOString().split('T')[0] : null;
+          const isFuture = ts && ts > now;
+          return {
+            date: dateStr,
+            report: item.message,
+            status: isFuture ? '⏳ 未发布' : '✅ 已发布',
+            _ts: ts,
+            _future: isFuture
+          };
+        });
+
+        if (onlyNext) {
+          const future = results.filter(r => r._future).sort((a, b) => a._ts - b._ts);
+          results = future.length ? [future[0]] : [];
+        }
+
+        return results;
+      })()
+
+  - map:
+      date: ${{ item.date }}
+      report: ${{ item.report }}
+      status: ${{ item.status }}
+
+  - limit: ${{ args.limit }}
+
+columns: [date, report, status]

package/src/clis/xueqiu/search.yaml

@@ -6,7 +6,9 @@ browser: true
 
 args:
   query:
+    positional: true
     type: str
+    required: true
     description: 搜索关键词，如 茅台、AAPL、腾讯
   limit:
     type: int
@@ -19,7 +21,6 @@ pipeline:
       (async () => {
         const query = ${{ args.query | json }};
         const count = ${{ args.limit }};
-        if (!query) throw new Error('Missing argument: query');
         const resp = await fetch(`https://xueqiu.com/stock/search.json?code=${encodeURIComponent(query)}&size=${count}`, {credentials: 'include'});
         if (!resp.ok) throw new Error('HTTP ' + resp.status + ' Hint: Not logged in?');
         const d = await resp.json();

package/src/clis/xueqiu/stock.yaml

@@ -6,7 +6,9 @@ browser: true
 
 args:
   symbol:
+    positional: true
     type: str
+    required: true
     description: 股票代码，如 SH600519、SZ000858、AAPL、00700
 
 pipeline:

package/src/clis/yahoo-finance/quote.ts

@@ -11,13 +11,12 @@ cli({
   domain: 'finance.yahoo.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'symbol', required: true, help: 'Stock ticker (e.g. AAPL, MSFT, TSLA)' },
+    { name: 'symbol', required: true, positional: true, help: 'Stock ticker (e.g. AAPL, MSFT, TSLA)' },
   ],
   columns: ['symbol', 'name', 'price', 'change', 'changePercent', 'open', 'high', 'low', 'volume', 'marketCap'],
   func: async (page, kwargs) => {
     const symbol = kwargs.symbol.toUpperCase().trim();
     await page.goto(`https://finance.yahoo.com/quote/${encodeURIComponent(symbol)}/`);
-    await page.wait(3);
     const data = await page.evaluate(`
       (async () => {
         const sym = '${symbol}';

package/src/clis/youtube/search.ts

@@ -11,7 +11,7 @@ cli({
   domain: 'www.youtube.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'query', required: true, help: 'Search query' },
+    { name: 'query', required: true, positional: true, help: 'Search query' },
     { name: 'limit', type: 'int', default: 20, help: 'Max results (max 50)' },
   ],
   columns: ['rank', 'title', 'channel', 'views', 'duration', 'url'],

package/src/clis/youtube/transcript.ts

@@ -25,7 +25,7 @@ cli({
   domain: 'www.youtube.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'url', required: true, help: 'YouTube video URL or video ID' },
+    { name: 'url', required: true, positional: true, help: 'YouTube video URL or video ID' },
     { name: 'lang', required: false, help: 'Language code (e.g. en, zh-Hans). Omit to auto-select' },
     { name: 'mode', required: false, default: 'grouped', help: 'Output mode: grouped (readable paragraphs) or raw (every segment)' },
   ],

package/src/clis/youtube/video.ts

@@ -11,7 +11,7 @@ cli({
   domain: 'www.youtube.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'url', required: true, help: 'YouTube video URL or video ID' },
+    { name: 'url', required: true, positional: true, help: 'YouTube video URL or video ID' },
   ],
   columns: ['field', 'value'],
   func: async (page, kwargs) => {

package/src/clis/zhihu/download.ts

@@ -92,7 +92,7 @@ cli({
   domain: 'zhuanlan.zhihu.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'url', required: true, help: 'Article URL (zhuanlan.zhihu.com/p/xxx)' },
+    { name: 'url', required: true, positional: true, help: 'Article URL (zhuanlan.zhihu.com/p/xxx)' },
     { name: 'output', default: './zhihu-articles', help: 'Output directory' },
     { name: 'download-images', type: 'boolean', default: false, help: 'Download images locally' },
   ],
@@ -104,7 +104,6 @@ cli({
 
     // Navigate to article page
     await page.goto(url);
-    await page.wait(3);
 
     // Extract article content
     const data = await page.evaluate(`

package/src/clis/zhihu/question.ts

@@ -7,7 +7,7 @@ cli({
   domain: 'www.zhihu.com',
   strategy: Strategy.COOKIE,
   args: [
-    { name: 'id', required: true, help: 'Question ID (numeric)' },
+    { name: 'id', required: true, positional: true, help: 'Question ID (numeric)' },
     { name: 'limit', type: 'int', default: 5, help: 'Number of answers' },
   ],
   columns: ['rank', 'author', 'votes', 'content'],

package/src/clis/zhihu/search.yaml

@@ -4,10 +4,11 @@ description: 知乎搜索
 domain: www.zhihu.com
 
 args:
-  keyword:
+  query:
+    positional: true
     type: str
     required: true
-    description: Search keyword
+    description: Search query
   limit:
     type: int
     default: 10
@@ -19,7 +20,7 @@ pipeline:
   - evaluate: |
       (async () => {
         const strip = (html) => (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/<em>/g, '').replace(/<\/em>/g, '').trim();
-        const keyword = ${{ args.keyword | json }};
+        const keyword = ${{ args.query | json }};
         const limit = ${{ args.limit }};
         const res = await fetch('https://www.zhihu.com/api/v4/search_v3?q=' + encodeURIComponent(keyword) + '&t=general&offset=0&limit=' + limit, {
           credentials: 'include'

package/src/commanderAdapter.ts

@@ -0,0 +1,120 @@
+/**
+ * Commander adapter: bridges Registry commands to Commander subcommands.
+ *
+ * This is a THIN adapter — it only handles:
+ * 1. Commander arg/option registration
+ * 2. Collecting kwargs from Commander's action args
+ * 3. Calling executeCommand (which handles browser sessions, validation, etc.)
+ * 4. Rendering output and errors
+ *
+ * All execution logic lives in execution.ts.
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { type CliCommand, fullName, getRegistry } from './registry.js';
+import { formatRegistryHelpText } from './serialization.js';
+import { render as renderOutput } from './output.js';
+import { executeCommand } from './execution.js';
+import { CliError } from './errors.js';
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Register a single CliCommand as a Commander subcommand.
+ */
+export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void {
+  if (siteCmd.commands.some((c: Command) => c.name() === cmd.name)) return;
+
+  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.addHelpText('after', formatRegistryHelpText(cmd));
+
+  subCmd.action(async (...actionArgs: unknown[]) => {
+    const actionOpts = actionArgs[positionalArgs.length] ?? {};
+    const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts as Record<string, unknown> : {};
+    const startTime = Date.now();
+
+    // ── Collect kwargs ──────────────────────────────────────────────────
+    const kwargs: Record<string, unknown> = {};
+    for (let i = 0; i < positionalArgs.length; i++) {
+      const v = actionArgs[i];
+      if (v !== undefined) kwargs[positionalArgs[i].name] = v;
+    }
+    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 = optionsRecord[arg.name] ?? optionsRecord[camelName];
+      if (v !== undefined) kwargs[arg.name] = v;
+    }
+
+    // ── Execute + render ────────────────────────────────────────────────
+    try {
+      const verbose = optionsRecord.verbose === true;
+      const format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
+      if (verbose) process.env.OPENCLI_VERBOSE = '1';
+
+      const result = await executeCommand(cmd, kwargs, verbose);
+
+      if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
+        console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
+      }
+      const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
+      renderOutput(result, {
+        fmt: format,
+        columns: resolved.columns,
+        title: `${resolved.site}/${resolved.name}`,
+        elapsed: (Date.now() - startTime) / 1000,
+        source: fullName(resolved),
+        footerExtra: resolved.footerExtra?.(kwargs),
+      });
+    } catch (err) {
+      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 (optionsRecord.verbose === true && err instanceof Error && err.stack) {
+        console.error(chalk.red(err.stack));
+      } else {
+        console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
+      }
+      process.exitCode = 1;
+    }
+  });
+}
+
+/**
+ * Register all commands from the registry onto a Commander program.
+ */
+export function registerAllCommands(
+  program: Command,
+  siteGroups: Map<string, Command>,
+): void {
+  for (const [, cmd] of getRegistry()) {
+    let siteCmd = siteGroups.get(cmd.site);
+    if (!siteCmd) {
+      siteCmd = program.command(cmd.site).description(`${cmd.site} commands`);
+      siteGroups.set(cmd.site, siteCmd);
+    }
+    registerCommandToProgram(siteCmd, cmd);
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,277 @@
+/**
+ * CLI discovery: finds YAML/TS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers all YAML commands instantly without runtime YAML parsing.
+ *    TS modules are loaded lazily only when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import { type CliCommand, type InternalCliCommand, type Arg, Strategy, registerCommand } from './registry.js';
+import { log } from './logger.js';
+import type { ManifestEntry } from './build-manifest.js';
+
+/** Plugins directory: ~/.opencli/plugins/ */
+export const PLUGINS_DIR = path.join(os.homedir(), '.opencli', 'plugins');
+const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+
+interface YamlArgDefinition {
+  type?: string;
+  default?: unknown;
+  required?: boolean;
+  positional?: boolean;
+  description?: string;
+  help?: string;
+  choices?: string[];
+}
+
+interface YamlCliDefinition {
+  site?: string;
+  name?: string;
+  description?: string;
+  domain?: string;
+  strategy?: string;
+  browser?: boolean;
+  args?: Record<string, YamlArgDefinition>;
+  columns?: string[];
+  pipeline?: Record<string, unknown>[];
+  timeout?: number;
+  navigateBefore?: boolean | string;
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function parseStrategy(rawStrategy: string | undefined, fallback: Strategy = Strategy.COOKIE): Strategy {
+  if (!rawStrategy) return fallback;
+  const key = rawStrategy.toUpperCase() as keyof typeof Strategy;
+  return Strategy[key] ?? fallback;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export async function discoverClis(...dirs: string[]): Promise<void> {
+  // Fast path: try manifest first (production / post-build)
+  for (const dir of dirs) {
+    const manifestPath = path.resolve(dir, '..', 'cli-manifest.json');
+    try {
+      await fs.promises.access(manifestPath);
+      await loadFromManifest(manifestPath, dir);
+      continue; // Skip filesystem scan for this directory
+    } catch {
+      // Fallback: runtime filesystem scan (development)
+      await discoverClisFromFs(dir);
+    }
+  }
+}
+
+/**
+ * Fast-path: register commands from pre-compiled manifest.
+ * YAML pipelines are inlined — zero YAML parsing at runtime.
+ * TS modules are deferred — loaded lazily on first execution.
+ */
+async function loadFromManifest(manifestPath: string, clisDir: string): Promise<void> {
+  try {
+    const raw = await fs.promises.readFile(manifestPath, 'utf-8');
+    const manifest = JSON.parse(raw) as ManifestEntry[];
+    for (const entry of manifest) {
+      if (entry.type === 'yaml') {
+        // YAML pipelines fully inlined in manifest — register directly
+        const strategy = parseStrategy(entry.strategy);
+        const cmd: CliCommand = {
+          site: entry.site,
+          name: entry.name,
+          description: entry.description ?? '',
+          domain: entry.domain,
+          strategy,
+          browser: entry.browser,
+          args: entry.args ?? [],
+          columns: entry.columns,
+          pipeline: entry.pipeline,
+          timeoutSeconds: entry.timeout,
+          source: `manifest:${entry.site}/${entry.name}`,
+          navigateBefore: entry.navigateBefore,
+        };
+        registerCommand(cmd);
+      } else if (entry.type === 'ts' && entry.modulePath) {
+        // TS adapters: register a lightweight stub.
+        // The actual module is loaded lazily on first executeCommand().
+        const strategy = parseStrategy(entry.strategy ?? 'cookie');
+        const modulePath = path.resolve(clisDir, entry.modulePath);
+        const cmd: InternalCliCommand = {
+          site: entry.site,
+          name: entry.name,
+          description: entry.description ?? '',
+          domain: entry.domain,
+          strategy,
+          browser: entry.browser ?? true,
+          args: entry.args ?? [],
+          columns: entry.columns,
+          timeoutSeconds: entry.timeout,
+          source: modulePath,
+          navigateBefore: entry.navigateBefore,
+          _lazy: true,
+          _modulePath: modulePath,
+        };
+        registerCommand(cmd);
+      }
+    }
+  } catch (err) {
+    log.warn(`Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
+  }
+}
+
+/**
+ * Fallback: traditional filesystem scan (used during development with tsx).
+ */
+async function discoverClisFromFs(dir: string): Promise<void> {
+  try { await fs.promises.access(dir); } catch { return; }
+  const promises: Promise<unknown>[] = [];
+  const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const site = entry.name;
+    const siteDir = path.join(dir, site);
+    const files = await fs.promises.readdir(siteDir);
+    for (const file of files) {
+      const filePath = path.join(siteDir, file);
+      if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+        promises.push(registerYamlCli(filePath, site));
+      } else if (
+        (file.endsWith('.js') && !file.endsWith('.d.js')) ||
+        (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))
+      ) {
+        if (!(await isCliModule(filePath))) continue;
+        promises.push(
+          import(pathToFileURL(filePath).href).catch((err) => {
+            log.warn(`Failed to load module ${filePath}: ${getErrorMessage(err)}`);
+          })
+        );
+      }
+    }
+  }
+  await Promise.all(promises);
+}
+
+async function registerYamlCli(filePath: string, defaultSite: string): Promise<void> {
+  try {
+    const raw = await fs.promises.readFile(filePath, 'utf-8');
+    const def = yaml.load(raw) as YamlCliDefinition | null;
+    if (!isRecord(def)) return;
+    const cliDef = def as YamlCliDefinition;
+
+    const site = cliDef.site ?? defaultSite;
+    const name = cliDef.name ?? path.basename(filePath, path.extname(filePath));
+    const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
+    const strategy = parseStrategy(strategyStr);
+    const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
+
+    const args: Arg[] = [];
+    if (cliDef.args && typeof cliDef.args === 'object') {
+      for (const [argName, argDef] of Object.entries(cliDef.args)) {
+        args.push({
+          name: argName,
+          type: argDef?.type ?? 'str',
+          default: argDef?.default,
+          required: argDef?.required ?? false,
+          positional: argDef?.positional ?? false,
+          help: argDef?.description ?? argDef?.help ?? '',
+          choices: argDef?.choices,
+        });
+      }
+    }
+
+    const cmd: CliCommand = {
+      site,
+      name,
+      description: cliDef.description ?? '',
+      domain: cliDef.domain,
+      strategy,
+      browser,
+      args,
+      columns: cliDef.columns,
+      pipeline: cliDef.pipeline,
+      timeoutSeconds: cliDef.timeout,
+      source: filePath,
+      navigateBefore: cliDef.navigateBefore,
+    };
+
+    registerCommand(cmd);
+  } catch (err) {
+    log.warn(`Failed to load ${filePath}: ${getErrorMessage(err)}`);
+  }
+}
+
+/**
+ * Discover and register plugins from ~/.opencli/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export async function discoverPlugins(): Promise<void> {
+  try { await fs.promises.access(PLUGINS_DIR); } catch { return; }
+  const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    await discoverPluginDir(path.join(PLUGINS_DIR, entry.name), entry.name);
+  }
+}
+
+/**
+ * Flat scan: read yaml/ts files directly in a plugin directory.
+ * Unlike discoverClisFromFs, this does NOT expect nested site subdirectories.
+ */
+async function discoverPluginDir(dir: string, site: string): Promise<void> {
+  const files = await fs.promises.readdir(dir);
+  const fileSet = new Set(files);
+  const promises: Promise<unknown>[] = [];
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+      promises.push(registerYamlCli(filePath, site));
+    } else if (file.endsWith('.js') && !file.endsWith('.d.js')) {
+      if (!(await isCliModule(filePath))) continue;
+      promises.push(
+        import(pathToFileURL(filePath).href).catch((err) => {
+          log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+        })
+      );
+    } else if (
+      file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')
+    ) {
+      // Skip .ts if a compiled .js sibling exists (production mode can't load .ts)
+      const jsFile = file.replace(/\.ts$/, '.js');
+      if (fileSet.has(jsFile)) continue;
+      if (!(await isCliModule(filePath))) continue;
+      promises.push(
+        import(pathToFileURL(filePath).href).catch((err) => {
+          log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+        })
+      );
+    }
+  }
+  await Promise.all(promises);
+}
+
+async function isCliModule(filePath: string): Promise<boolean> {
+  try {
+    const source = await fs.promises.readFile(filePath, 'utf-8');
+    return CLI_MODULE_PATTERN.test(source);
+  } catch (err) {
+    log.warn(`Failed to inspect module ${filePath}: ${getErrorMessage(err)}`);
+    return false;
+  }
+}