@jackwener/opencli 1.4.1 → 1.5.0

package/src/browser/errors.ts

@@ -5,38 +5,37 @@
  * The daemon architecture has a single failure mode: daemon not reachable or extension not connected.
  */
 
-import { BrowserConnectError } from '../errors.js';
+import { BrowserConnectError, type BrowserConnectKind } from '../errors.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 
-export type ConnectFailureKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
+// Re-export so callers don't need to import from two places
+export type ConnectFailureKind = BrowserConnectKind;
 
 export function formatBrowserConnectError(kind: ConnectFailureKind, detail?: string): BrowserConnectError {
   switch (kind) {
     case 'daemon-not-running':
       return new BrowserConnectError(
-        'Cannot connect to opencli daemon.' +
-        (detail ? `\n\n${detail}` : ''),
-        'The daemon should start automatically. If it doesn\'t, try:\n' +
-        '  node dist/daemon.js\n' +
-        `Make sure port ${DEFAULT_DAEMON_PORT} is available.`,
+        'Cannot connect to opencli daemon.' + (detail ? `\n\n${detail}` : ''),
+        `The daemon should auto-start. If it keeps failing, make sure port ${DEFAULT_DAEMON_PORT} is available.`,
+        kind,
       );
     case 'extension-not-connected':
       return new BrowserConnectError(
-        'opencli Browser Bridge extension is not connected.' +
-        (detail ? `\n\n${detail}` : ''),
-        'Please install the extension:\n' +
-        '  1. Download from GitHub Releases\n' +
-        '  2. Open chrome://extensions/ → Enable Developer Mode\n' +
-        '  3. Click "Load unpacked" → select the extension folder\n' +
-        '  4. Make sure Chrome is running',
+        'Browser Bridge extension is not connected.' + (detail ? `\n\n${detail}` : ''),
+        'Install the extension from GitHub Releases, then reload.',
+        kind,
       );
     case 'command-failed':
       return new BrowserConnectError(
         `Browser command failed: ${detail ?? 'unknown error'}`,
+        undefined,
+        kind,
       );
     default:
       return new BrowserConnectError(
         detail ?? 'Failed to connect to browser',
+        undefined,
+        kind,
       );
   }
 }

package/src/browser/mcp.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import type { IPage } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
 import { Page } from './page.js';
 import { isDaemonRunning, isExtensionConnected } from './daemon-client.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
@@ -18,7 +19,7 @@ export type BrowserBridgeState = 'idle' | 'connecting' | 'connected' | 'closing'
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
  */
-export class BrowserBridge {
+export class BrowserBridge implements IBrowserFactory {
   private _state: BrowserBridgeState = 'idle';
   private _page: Page | null = null;
   private _daemonProc: ChildProcess | null = null;

package/src/build-manifest.test.ts

@@ -143,4 +143,27 @@ describe('manifest helper rules', () => {
       modulePath: 'xueqiu/fund-holdings.js',
     });
   });
+
+  it('captures deprecated metadata for TS adapters', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
+    tempDirs.push(dir);
+    const file = path.join(dir, 'legacy.ts');
+    fs.writeFileSync(file, `
+      import { cli } from '../../registry.js';
+      cli({
+        site: 'demo',
+        name: 'legacy',
+        description: 'legacy command',
+        deprecated: 'legacy is deprecated',
+        replacedBy: 'opencli demo new',
+      });
+    `);
+
+    expect(scanTs(file, 'demo')).toMatchObject({
+      site: 'demo',
+      name: 'legacy',
+      deprecated: 'legacy is deprecated',
+      replacedBy: 'opencli demo new',
+    });
+  });
 });

package/src/build-manifest.ts

@@ -38,6 +38,8 @@ export interface ManifestEntry {
   columns?: string[];
   pipeline?: Record<string, unknown>[];
   timeout?: number;
+  deprecated?: boolean | string;
+  replacedBy?: string;
   /** 'yaml' or 'ts' — determines how executeCommand loads the handler */
   type: 'yaml' | 'ts';
   /** Relative path from clis/ dir, e.g. 'bilibili/hot.yaml' or 'bilibili/search.js' */
@@ -46,7 +48,7 @@ export interface ManifestEntry {
   navigateBefore?: boolean | string;
 }
 
-import type { YamlCliDefinition } from './yaml-schema.js';
+import { type YamlCliDefinition, parseYamlArgs } from './yaml-schema.js';
 
 import { isRecord } from './utils.js';
 
@@ -173,20 +175,7 @@ function scanYaml(filePath: string, site: string): ManifestEntry | null {
     const strategy = strategyStr.toUpperCase();
     const browser = cliDef.browser ?? (strategy !== 'PUBLIC');
 
-    const args: ManifestEntry['args'] = [];
-    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 === true || undefined,
-          help: argDef?.description ?? argDef?.help ?? '',
-          choices: argDef?.choices,
-        });
-      }
-    }
+    const args = parseYamlArgs(cliDef.args);
 
     return {
       site: cliDef.site ?? site,
@@ -199,6 +188,8 @@ function scanYaml(filePath: string, site: string): ManifestEntry | null {
       columns: cliDef.columns,
       pipeline: cliDef.pipeline,
       timeout: cliDef.timeout,
+      deprecated: (cliDef as Record<string, unknown>).deprecated as boolean | string | undefined,
+      replacedBy: (cliDef as Record<string, unknown>).replacedBy as string | undefined,
       type: 'yaml',
       navigateBefore: cliDef.navigateBefore,
     };
@@ -269,6 +260,17 @@ export function scanTs(filePath: string, site: string): ManifestEntry | null {
       if (navStringMatch) entry.navigateBefore = navStringMatch[1];
     }
 
+    const deprecatedBoolMatch = src.match(/deprecated\s*:\s*(true|false)/);
+    if (deprecatedBoolMatch) {
+      entry.deprecated = deprecatedBoolMatch[1] === 'true';
+    } else {
+      const deprecatedStringMatch = src.match(/deprecated\s*:\s*['"`]([^'"`]+)['"`]/);
+      if (deprecatedStringMatch) entry.deprecated = deprecatedStringMatch[1];
+    }
+
+    const replacedByMatch = src.match(/replacedBy\s*:\s*['"`]([^'"`]+)['"`]/);
+    if (replacedByMatch) entry.replacedBy = replacedByMatch[1];
+
     return entry;
   } catch (err) {
     // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
@@ -338,6 +340,29 @@ function main(): void {
   const yamlCount = manifest.filter(e => e.type === 'yaml').length;
   const tsCount = manifest.filter(e => e.type === 'ts').length;
   console.log(`✅ Manifest compiled: ${manifest.length} entries (${yamlCount} YAML, ${tsCount} TS) → ${OUTPUT}`);
+
+  // Restore executable permissions on bin entries.
+  // tsc does not preserve the +x bit, so after a clean rebuild the CLI
+  // entry-point loses its executable permission, causing "Permission denied".
+  // See: https://github.com/jackwener/opencli/issues/446
+  if (process.platform !== 'win32') {
+    const pkgPath = path.resolve(__dirname, '..', 'package.json');
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const bins: Record<string, string> = typeof pkg.bin === 'string'
+        ? { [pkg.name ?? 'cli']: pkg.bin }
+        : pkg.bin ?? {};
+      for (const binPath of Object.values(bins)) {
+        const abs = path.resolve(__dirname, '..', binPath);
+        if (fs.existsSync(abs)) {
+          fs.chmodSync(abs, 0o755);
+          console.log(`✅ Restored executable permission: ${binPath}`);
+        }
+      }
+    } catch {
+      // Best-effort; never break the build for a permission fix.
+    }
+  }
 }
 
 const entrypoint = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null;

package/src/capabilityRouting.ts

@@ -1,6 +1,7 @@
 import { Strategy, type CliCommand } from './registry.js';
 
-const BROWSER_ONLY_STEPS = new Set([
+/** Pipeline steps that require a live browser session. */
+export const BROWSER_ONLY_STEPS = new Set([
   'navigate',
   'click',
   'type',

package/src/cli.ts

@@ -258,9 +258,17 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       const { installPlugin } = await import('./plugin.js');
       const { discoverPlugins } = await import('./discovery.js');
       try {
-        const name = installPlugin(source);
+        const result = installPlugin(source);
         await discoverPlugins();
-        console.log(chalk.green(`✅ Plugin "${name}" installed successfully. Commands are ready to use.`));
+        if (Array.isArray(result)) {
+          if (result.length === 0) {
+            console.log(chalk.yellow('No plugins were installed (all skipped or incompatible).'));
+          } else {
+            console.log(chalk.green(`\u2705 Installed ${result.length} plugin(s) from monorepo: ${result.join(', ')}`));
+          }
+        } else {
+          console.log(chalk.green(`\u2705 Plugin "${result}" installed successfully. Commands are ready to use.`));
+        }
       } catch (err) {
         console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
         process.exitCode = 1;
@@ -368,12 +376,36 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       console.log();
       console.log(chalk.bold('  Installed plugins'));
       console.log();
+
+      // Group by monorepo
+      const standalone = plugins.filter((p) => !p.monorepoName);
+      const monoGroups = new Map<string, typeof plugins>();
       for (const p of plugins) {
+        if (!p.monorepoName) continue;
+        const g = monoGroups.get(p.monorepoName) ?? [];
+        g.push(p);
+        monoGroups.set(p.monorepoName, g);
+      }
+
+      for (const p of standalone) {
         const version = p.version ? chalk.green(` @${p.version}`) : '';
+        const desc = p.description ? chalk.dim(` — ${p.description}`) : '';
         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)}${version}${cmds}${src}`);
+        console.log(`  ${chalk.cyan(p.name)}${version}${desc}${cmds}${src}`);
       }
+
+      for (const [mono, group] of monoGroups) {
+        console.log();
+        console.log(chalk.bold.magenta(`  📦 ${mono}`) + chalk.dim(' (monorepo)'));
+        for (const p of group) {
+          const version = p.version ? chalk.green(` @${p.version}`) : '';
+          const desc = p.description ? chalk.dim(` — ${p.description}`) : '';
+          const cmds = p.commands.length > 0 ? chalk.dim(` (${p.commands.join(', ')})`) : '';
+          console.log(`    ${chalk.cyan(p.name)}${version}${desc}${cmds}`);
+        }
+      }
+
       console.log();
       console.log(chalk.dim(`  ${plugins.length} plugin(s) installed`));
       console.log();

package/src/clis/36kr/article.ts

@@ -0,0 +1,69 @@
+/**
+ * 36kr article detail — INTERCEPT strategy.
+ *
+ * Fetches the full content of a 36kr article given its ID or URL.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import type { IPage } from '../../types.js';
+
+/** Extract article ID from a full URL or a bare numeric ID string */
+function parseArticleId(input: string): string {
+  const m = input.match(/\/p\/(\d+)/);
+  return m ? m[1] : input.replace(/\D/g, '');
+}
+
+cli({
+  site: '36kr',
+  name: 'article',
+  description: '获取36氪文章正文内容',
+  domain: 'www.36kr.com',
+  strategy: Strategy.INTERCEPT,
+  args: [
+    { name: 'id', positional: true, required: true, help: 'Article ID or full 36kr article URL' },
+  ],
+  columns: ['field', 'value'],
+  func: async (page: IPage, args) => {
+    const articleId = parseArticleId(String(args.id ?? ''));
+    if (!articleId) {
+      throw new CliError('INVALID_ARGUMENT', 'Invalid article ID or URL');
+    }
+
+    await page.installInterceptor('36kr.com/api');
+    await page.goto(`https://www.36kr.com/p/${articleId}`);
+    await page.wait(5);
+
+    const data: any = await page.evaluate(`
+      (() => {
+        // Title: 36kr uses class "article-title" on h1
+        const title = document.querySelector('.article-title, h1')?.textContent?.trim() || '';
+        // Author: second .author-name (first is empty nav link, second has real name)
+        const authorEls = document.querySelectorAll('.author-name');
+        const author = Array.from(authorEls).map(el => el.textContent?.trim()).filter(Boolean)[0] || '';
+        // Date: 36kr uses class "title-icon-item item-time" for the publish date
+        const dateRaw = document.querySelector('.item-time')?.textContent?.trim() || '';
+        const date = dateRaw.replace(/^[·\s]+/, '').trim();
+        // Article body paragraphs
+        const bodyEls = document.querySelectorAll('[class*="article-content"] p, [class*="rich-text"] p, .article p');
+        const body = Array.from(bodyEls)
+          .map(el => el.textContent?.trim())
+          .filter(t => t && t.length > 10)
+          .join(' ')
+          .slice(0, 800);
+        return { title, author, date, body };
+      })()
+    `);
+
+    if (!data?.title) {
+      throw new CliError('NOT_FOUND', 'Article not found or failed to load', 'Check the article ID');
+    }
+
+    return [
+      { field: 'title',  value: data.title },
+      { field: 'author', value: data.author || '-' },
+      { field: 'date',   value: data.date || '-' },
+      { field: 'url',    value: `https://36kr.com/p/${articleId}` },
+      { field: 'body',   value: data.body || '-' },
+    ];
+  },
+});

package/src/clis/36kr/hot.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildHotListUrl, getShanghaiDate } from './hot.js';
+
+describe('36kr/hot date routing', () => {
+  it('formats dates in Asia/Shanghai instead of UTC', () => {
+    const date = new Date('2026-03-25T18:30:00.000Z');
+    expect(getShanghaiDate(date)).toBe('2026-03-26');
+  });
+
+  it('builds dated hot-list routes with Shanghai-local date', () => {
+    const date = new Date('2026-03-25T18:30:00.000Z');
+    expect(buildHotListUrl('renqi', date)).toBe('https://www.36kr.com/hot-list/renqi/2026-03-26/1');
+  });
+
+  it('keeps catalog on the static route', () => {
+    expect(buildHotListUrl('catalog')).toBe('https://www.36kr.com/hot-list/catalog');
+  });
+});

package/src/clis/36kr/hot.ts

@@ -0,0 +1,100 @@
+/**
+ * 36kr hot-list — INTERCEPT strategy.
+ *
+ * Navigates to the 36kr hot-list page and scrapes rendered article links.
+ * Supports category types: renqi (人气), zonghe (综合), shoucang (收藏), catalog (综合热门).
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import type { IPage } from '../../types.js';
+
+const TYPE_MAP: Record<string, string> = {
+  renqi:   '人气榜',
+  zonghe:  '综合榜',
+  shoucang: '收藏榜',
+  catalog: '热门资讯',
+};
+
+function getShanghaiDate(date = new Date()): string {
+  // Shanghai stays on UTC+8 year-round, so a fixed offset is sufficient here
+  // and avoids the slow Intl timezone path that timed out on Windows CI.
+  return new Date(date.getTime() + 8 * 60 * 60 * 1000).toISOString().slice(0, 10);
+}
+
+function buildHotListUrl(listType: string, date = new Date()): string {
+  if (listType === 'catalog') {
+    return 'https://www.36kr.com/hot-list/catalog';
+  }
+
+  return `https://www.36kr.com/hot-list/${listType}/${getShanghaiDate(date)}/1`;
+}
+
+cli({
+  site: '36kr',
+  name: 'hot',
+  description: '36氪热榜 — trending articles (renqi/zonghe/shoucang/catalog)',
+  domain: 'www.36kr.com',
+  strategy: Strategy.INTERCEPT,
+  args: [
+    { name: 'limit', type: 'int', default: 20, help: 'Number of items (max 50)' },
+    {
+      name: 'type',
+      type: 'string',
+      default: 'catalog',
+      help: 'List type: renqi (人气), zonghe (综合), shoucang (收藏), catalog (热门资讯)',
+    },
+  ],
+  columns: ['rank', 'title', 'url'],
+  func: async (page: IPage, args) => {
+    const count = Math.min(Number(args.limit) || 20, 50);
+    const listType = String(args.type ?? 'catalog');
+
+    if (!TYPE_MAP[listType]) {
+      throw new CliError(
+        'INVALID_ARGUMENT',
+        `Unknown type "${listType}". Valid types: ${Object.keys(TYPE_MAP).join(', ')}`,
+      );
+    }
+
+    const url = buildHotListUrl(listType);
+
+    await page.installInterceptor('36kr.com/api');
+    await page.goto(url);
+    await page.wait(6);
+
+    // Scrape rendered article links from DOM (deduplicated)
+    const domItems: any = await page.evaluate(`
+      (() => {
+        const seen = new Set();
+        const results = [];
+        const links = document.querySelectorAll('a[href*="/p/"]');
+        for (const el of links) {
+          const href = el.getAttribute('href') || '';
+          const title = el.textContent?.trim() || '';
+          if (!title || title.length < 5 || seen.has(href) || seen.has(title)) continue;
+          seen.add(href);
+          seen.add(title);
+          results.push({ title, url: href.startsWith('http') ? href : 'https://36kr.com' + href });
+        }
+        return results;
+      })()
+    `);
+
+    const items = Array.isArray(domItems) ? (domItems as any[]) : [];
+    if (items.length === 0) {
+      throw new CliError(
+        'NO_DATA',
+        'Could not retrieve 36kr hot list',
+        '36kr may have changed its DOM structure',
+      );
+    }
+
+    return items.slice(0, count).map((item: any, i: number) => ({
+      rank: i + 1,
+      title: item.title,
+      url: item.url,
+    }));
+  },
+});
+
+export { buildHotListUrl, getShanghaiDate };

package/src/clis/36kr/news.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+const SAMPLE_RSS = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0"><channel><title>36氪</title>
+<item>
+  <title>红杉中国领投AI公司「示例」，金额近2亿元</title>
+  <link><![CDATA[https://36kr.com/p/1111111111111111?f=rss]]></link>
+  <pubDate>2026-03-26 10:00:00  +0800</pubDate>
+</item>
+<item>
+  <title>马斯克旗下xAI估值突破1000亿美元</title>
+  <link><![CDATA[https://36kr.com/p/2222222222222222?f=rss]]></link>
+  <pubDate>2026-03-26 09:00:00  +0800</pubDate>
+</item>
+<item>
+  <title>OpenAI发布GPT-5，多模态能力大幅提升</title>
+  <link><![CDATA[https://36kr.com/p/3333333333333333?f=rss]]></link>
+  <pubDate>2026-03-25 20:00:00  +0800</pubDate>
+</item>
+</channel></rss>`;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('36kr/news RSS parsing', () => {
+  it('parses RSS feed into ranked news items', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+      text: async () => SAMPLE_RSS,
+    } as Response);
+
+    // Direct RSS parse test using the same regex logic as news.ts
+    const xml = SAMPLE_RSS;
+    const items: { rank: number; title: string; date: string; url: string }[] = [];
+    const itemRegex = /<item>([\s\S]*?)<\/item>/g;
+    let match;
+    while ((match = itemRegex.exec(xml)) && items.length < 10) {
+      const block = match[1];
+      const title = block.match(/<title>([\s\S]*?)<\/title>/)?.[1]?.trim() ?? '';
+      const url =
+        block.match(/<link><!\[CDATA\[(.*?)\]\]>/)?.[1] ??
+        block.match(/<link>(.*?)<\/link>/)?.[1] ??
+        '';
+      const pubDate = block.match(/<pubDate>(.*?)<\/pubDate>/)?.[1]?.trim() ?? '';
+      const date = pubDate.slice(0, 10);
+      if (title) items.push({ rank: items.length + 1, title, date, url: url.trim() });
+    }
+
+    expect(items).toHaveLength(3);
+    expect(items[0].rank).toBe(1);
+    expect(items[0].title).toBe('红杉中国领投AI公司「示例」，金额近2亿元');
+    expect(items[0].date).toBe('2026-03-26');
+    expect(items[0].url).toBe('https://36kr.com/p/1111111111111111?f=rss');
+  });
+
+  it('respects limit — returns at most N items', async () => {
+    const xml = SAMPLE_RSS;
+    const limit = 2;
+    const items: { rank: number; title: string; date: string; url: string }[] = [];
+    const itemRegex = /<item>([\s\S]*?)<\/item>/g;
+    let match;
+    while ((match = itemRegex.exec(xml)) && items.length < limit) {
+      const block = match[1];
+      const title = block.match(/<title>([\s\S]*?)<\/title>/)?.[1]?.trim() ?? '';
+      const url = block.match(/<link><!\[CDATA\[(.*?)\]\]>/)?.[1] ?? '';
+      const pubDate = block.match(/<pubDate>(.*?)<\/pubDate>/)?.[1]?.trim() ?? '';
+      const date = pubDate.slice(0, 10);
+      if (title) items.push({ rank: items.length + 1, title, date, url: url.trim() });
+    }
+    expect(items).toHaveLength(2);
+  });
+
+  it('skips items with empty title', async () => {
+    const xml = `<rss><channel>
+      <item><title></title><link>https://36kr.com/p/0</link><pubDate>2026-01-01</pubDate></item>
+      <item><title>有标题的文章</title><link>https://36kr.com/p/1</link><pubDate>2026-01-01</pubDate></item>
+    </channel></rss>`;
+    const items: any[] = [];
+    const itemRegex = /<item>([\s\S]*?)<\/item>/g;
+    let match;
+    while ((match = itemRegex.exec(xml))) {
+      const block = match[1];
+      const title = block.match(/<title>([\s\S]*?)<\/title>/)?.[1]?.trim() ?? '';
+      if (title) items.push({ title });
+    }
+    expect(items).toHaveLength(1);
+    expect(items[0].title).toBe('有标题的文章');
+  });
+});

package/src/clis/36kr/news.ts

@@ -0,0 +1,54 @@
+/**
+ * 36kr latest news — public RSS feed, no browser needed.
+ */
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: '36kr',
+  name: 'news',
+  description: 'Latest tech/startup news from 36kr (36氪)',
+  domain: 'www.36kr.com',
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: 'limit', type: 'int', default: 20, help: 'Number of articles (max 50)' },
+  ],
+  columns: ['rank', 'title', 'summary', 'date', 'url'],
+  func: async (_page, kwargs) => {
+    const count = Math.min(kwargs.limit || 20, 50);
+    const resp = await fetch('https://www.36kr.com/feed', {
+      headers: { 'User-Agent': 'Mozilla/5.0 (compatible; opencli/1.0)' },
+    });
+    if (!resp.ok) return [];
+    const xml = await resp.text();
+
+    const items: { rank: number; title: string; summary: string; date: string; url: string }[] = [];
+    const itemRegex = /<item>([\s\S]*?)<\/item>/g;
+    let match;
+    while ((match = itemRegex.exec(xml)) && items.length < count) {
+      const block = match[1];
+      const title = block.match(/<title>([\s\S]*?)<\/title>/)?.[1]?.trim() ?? '';
+      const url =
+        block.match(/<link><!\[CDATA\[(.*?)\]\]>/)?.[1] ??
+        block.match(/<link>(.*?)<\/link>/)?.[1] ??
+        '';
+      const pubDate = block.match(/<pubDate>(.*?)<\/pubDate>/)?.[1]?.trim() ?? '';
+      const date = pubDate.slice(0, 10);
+      // Extract plain-text summary from HTML description (first ~120 chars)
+      const rawDesc = block.match(/<description><!\[CDATA\[([\s\S]*?)\]\]>/)?.[1] ?? '';
+      const summary = rawDesc
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 120);
+
+      if (title) {
+        items.push({ rank: items.length + 1, title, summary, date, url: url.trim() });
+      }
+    }
+    return items;
+  },
+});