fix(wikipedia): fix search arg name + add random and trending commands (#231)

* fix(wikipedia): fix search arg name + add random and trending commands

- fix: search.ts referenced `args.keyword` but the argument is defined
  as `query`, causing the search term to always be undefined
- feat: add `random` command (random article summary via REST API)
- feat: add `trending` command (most-read articles, yesterday's data)

All commands are PUBLIC strategy, no browser required, reuse wikiFetch.

* refactor(wikipedia): extract shared types + add docs for random/trending

- Extract WikiSummary, WikiMostReadArticle types to utils.ts
- Extract EXTRACT_MAX_LEN/DESC_MAX_LEN constants
- Add formatSummaryRow() helper to eliminate duplicate mapping in
  summary.ts and random.ts
- Update docs with random and trending command examples

---------

Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: Astro-Han

docs/adapters/browser/wikipedia.md

@@ -8,6 +8,8 @@
 |---------|-------------|
 | `opencli wikipedia search` | Search Wikipedia articles |
 | `opencli wikipedia summary` | Get Wikipedia article summary |
+| `opencli wikipedia random` | Get a random Wikipedia article |
+| `opencli wikipedia trending` | Most-read articles (yesterday) |
 
 ## Usage Examples
 
@@ -16,10 +18,17 @@
 opencli wikipedia search "quantum computing" --limit 10
 
 # Get article summary
-opencli wikipedia summary --title "Artificial intelligence"
+opencli wikipedia summary "Artificial intelligence"
 
-# Search in other languages
+# Get a random article
+opencli wikipedia random
+
+# Most-read articles (yesterday)
+opencli wikipedia trending --limit 5
+
+# Use with other languages
 opencli wikipedia search "人工智能" --lang zh
+opencli wikipedia random --lang ja
 
 # JSON output
 opencli wikipedia search "Rust" -f json

src/clis/wikipedia/random.ts

@@ -0,0 +1,19 @@
+import { CliError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { type WikiSummary, formatSummaryRow, wikiFetch } from './utils.js';
+
+cli({
+  site: 'wikipedia',
+  name: 'random',
+  description: 'Get a random Wikipedia article',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [{ name: 'lang', default: 'en', help: 'Language code (e.g. en, zh, ja)' }],
+  columns: ['title', 'description', 'extract', 'url'],
+  func: async (_page, args) => {
+    const lang = args.lang || 'en';
+    const data = (await wikiFetch(lang, '/api/rest_v1/page/random/summary')) as WikiSummary;
+    if (!data?.title) throw new CliError('NOT_FOUND', 'No random article returned', 'Try again');
+    return [formatSummaryRow(data, lang)];
+  },
+});

src/clis/wikipedia/search.ts

@@ -1,8 +1,11 @@
-import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
 import { wikiFetch } from './utils.js';
 
-interface WikiSearchResult { title: string; snippet: string; }
+interface WikiSearchResult {
+  title: string;
+  snippet: string;
+}
 
 cli({
   site: 'wikipedia',
@@ -19,8 +22,11 @@ cli({
   func: async (_page, args) => {
     const limit = Math.max(1, Math.min(Number(args.limit), 50));
     const lang = args.lang || 'en';
-    const q = encodeURIComponent(args.keyword);
-    const data = await wikiFetch(lang, `/w/api.php?action=query&list=search&srsearch=${q}&srlimit=${limit}&format=json&utf8=1`) as { query?: { search?: WikiSearchResult[] } };
+    const q = encodeURIComponent(args.query);
+    const data = (await wikiFetch(
+      lang,
+      `/w/api.php?action=query&list=search&srsearch=${q}&srlimit=${limit}&format=json&utf8=1`,
+    )) as { query?: { search?: WikiSearchResult[] } };
     const results = data?.query?.search;
     if (!results?.length) throw new CliError('NOT_FOUND', 'No articles found', 'Try a different keyword');
     return results.map((r) => ({

src/clis/wikipedia/summary.ts

@@ -1,6 +1,6 @@
-import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
-import { wikiFetch } from './utils.js';
+import { cli, Strategy } from '../../registry.js';
+import { type WikiSummary, formatSummaryRow, wikiFetch } from './utils.js';
 
 cli({
   site: 'wikipedia',
@@ -16,13 +16,8 @@ cli({
   func: async (_page, args) => {
     const lang = args.lang || 'en';
     const title = encodeURIComponent(args.title.replace(/ /g, '_'));
-    const data = await wikiFetch(lang, `/api/rest_v1/page/summary/${title}`) as { title?: string; description?: string; extract?: string; content_urls?: { desktop?: { page?: string } } };
+    const data = (await wikiFetch(lang, `/api/rest_v1/page/summary/${title}`)) as WikiSummary;
     if (!data?.title) throw new CliError('NOT_FOUND', `Article "${args.title}" not found`, 'Try searching first: opencli wikipedia search <keyword>');
-    return [{
-      title: data.title,
-      description: data.description ?? '-',
-      extract: (data.extract ?? '').slice(0, 300),
-      url: data.content_urls?.desktop?.page ?? `https://${lang}.wikipedia.org/wiki/${title}`,
-    }];
+    return [formatSummaryRow(data, lang)];
   },
 });

src/clis/wikipedia/trending.ts

@@ -0,0 +1,41 @@
+import { CliError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { DESC_MAX_LEN, type WikiMostReadArticle, wikiFetch } from './utils.js';
+
+cli({
+  site: 'wikipedia',
+  name: 'trending',
+  description: 'Most-read Wikipedia articles (yesterday)',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'limit', type: 'int', default: 10, help: 'Max results' },
+    { name: 'lang', default: 'en', help: 'Language code (e.g. en, zh, ja)' },
+  ],
+  columns: ['rank', 'title', 'description', 'views'],
+  func: async (_page, args) => {
+    const lang = args.lang || 'en';
+    const limit = Math.max(1, Math.min(Number(args.limit), 50));
+
+    // Use yesterday's UTC date — Wikipedia API expects UTC and yesterday
+    // guarantees data availability (today's aggregation may be incomplete).
+    const d = new Date(Date.now() - 86_400_000);
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(d.getUTCDate()).padStart(2, '0');
+
+    const data = (await wikiFetch(lang, `/api/rest_v1/feed/featured/${yyyy}/${mm}/${dd}`)) as {
+      mostread?: { articles?: WikiMostReadArticle[] };
+    };
+    const articles = data?.mostread?.articles;
+    if (!articles?.length)
+      throw new CliError('NOT_FOUND', 'No trending articles available', 'Try a different language with --lang');
+
+    return articles.slice(0, limit).map((a, i) => ({
+      rank: i + 1,
+      title: a.title ?? '-',
+      description: (a.description ?? '-').slice(0, DESC_MAX_LEN),
+      views: a.views ?? 0,
+    }));
+  },
+});

src/clis/wikipedia/utils.ts

@@ -8,6 +8,27 @@
 
 import { CliError } from '../../errors.js';
 
+/** Maximum character length for article extract fields. */
+export const EXTRACT_MAX_LEN = 300;
+
+/** Maximum character length for short description fields. */
+export const DESC_MAX_LEN = 80;
+
+/** Response shape shared by /page/summary and /page/random/summary endpoints. */
+export interface WikiSummary {
+  title?: string;
+  description?: string;
+  extract?: string;
+  content_urls?: { desktop?: { page?: string } };
+}
+
+/** Article entry returned by the /feed/featured most-read endpoint. */
+export interface WikiMostReadArticle {
+  title?: string;
+  description?: string;
+  views?: number;
+}
+
 export async function wikiFetch(lang: string, path: string): Promise<unknown> {
   const url = `https://${lang}.wikipedia.org${path}`;
   const resp = await fetch(url, {
@@ -18,3 +39,13 @@ export async function wikiFetch(lang: string, path: string): Promise<unknown> {
   }
   return resp.json();
 }
+
+/** Map a WikiSummary API response to the standard output row. */
+export function formatSummaryRow(data: WikiSummary, lang: string) {
+  return {
+    title: data.title!,
+    description: data.description ?? '-',
+    extract: (data.extract ?? '').slice(0, EXTRACT_MAX_LEN),
+    url: data.content_urls?.desktop?.page ?? `https://${lang}.wikipedia.org`,
+  };
+}