@jackwener/opencli 1.7.12 → 1.7.13

package/clis/weixin/search.test.js

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { __test__ } from './search.js';
+
+describe('weixin search command', () => {
+    const command = getRegistry().get('weixin/search');
+
+    it('registers as a public browser command', () => {
+        expect(command).toBeDefined();
+        expect(command.site).toBe('weixin');
+        expect(command.strategy).toBe('public');
+        expect(command.browser).toBe(true);
+    });
+
+    it('rejects empty queries before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+
+        await expect(command.func(page, { query: '   ' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('rejects invalid page and limit values before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+
+        await expect(command.func(page, { query: 'AI', page: 0 })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        await expect(command.func(page, { query: 'AI', limit: 11 })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        await expect(command.func(page, { query: 'AI', limit: '2abc' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('uses page and limit while preserving per-page ranking', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                blocked: false,
+                empty: false,
+                cardCount: 2,
+                invalidCount: 0,
+                rows: [
+                    {
+                        title: 'First article',
+                        url: 'https://weixin.sogou.com/link?url=abc',
+                        summary: 'First summary',
+                        publish_time: '2小时前',
+                    },
+                    {
+                        title: 'Second article',
+                        url: 'https://weixin.sogou.com/link?url=def',
+                        summary: 'Second summary',
+                        publish_time: '1小时前',
+                    },
+                ],
+            }),
+        };
+
+        const result = await command.func(page, { query: 'AI', page: 2, limit: 1 });
+
+        expect(page.goto).toHaveBeenCalledWith('https://weixin.sogou.com/weixin?query=AI&type=2&page=2&ie=utf8');
+        expect(result).toEqual([
+            {
+                rank: 11,
+                page: 2,
+                title: 'First article',
+                url: 'https://weixin.sogou.com/link?url=abc',
+                summary: 'First summary',
+                publish_time: '2小时前',
+            },
+        ]);
+    });
+
+    it('preserves browser-side cleanup regex escapes', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                blocked: false,
+                empty: false,
+                cardCount: 1,
+                invalidCount: 0,
+                rows: [
+                    {
+                        title: 'Article',
+                        url: 'https://weixin.sogou.com/link?url=abc',
+                        summary: 'Summary',
+                        publish_time: '2024-4-28',
+                    },
+                ],
+            }),
+        };
+
+        await command.func(page, { query: 'AI' });
+
+        const script = page.evaluate.mock.calls[0][0];
+        expect(script).toContain(".replace(/\\s+/g, ' ')");
+        expect(script).toContain(".replace(/document\\.write\\(timeConvert\\('\\d+'\\)\\)/g, '')");
+    });
+
+    it('maps browser navigation failures to CommandExecutionError', async () => {
+        const page = {
+            goto: vi.fn().mockRejectedValue(new Error('net::ERR_FAILED')),
+        };
+
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('fails fast on unreadable payloads, verification blocks, and partial card extraction', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn(),
+        };
+
+        page.evaluate.mockResolvedValueOnce(null);
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+
+        page.evaluate.mockResolvedValueOnce({ blocked: true, empty: false, cardCount: 0, invalidCount: 0, rows: [] });
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+
+        page.evaluate.mockResolvedValueOnce({ blocked: false, empty: false, cardCount: 2, invalidCount: 1, rows: [{ title: 'Article', url: 'https://example.com' }] });
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('distinguishes explicit empty result pages from selector drift', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn()
+                .mockResolvedValueOnce({ blocked: false, empty: true, cardCount: 0, invalidCount: 0, rows: [] })
+                .mockResolvedValueOnce({ blocked: false, empty: false, cardCount: 0, invalidCount: 0, rows: [] }),
+        };
+
+        await expect(command.func(page, { query: 'no-result' })).rejects.toMatchObject({
+            name: 'EmptyResultError',
+            code: 'EMPTY_RESULT',
+        });
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('extracts browser DOM payload without silently dropping malformed result cards', async () => {
+        const document = {
+            body: { innerText: 'Article title Summary' },
+            querySelector: vi.fn(() => null),
+            querySelectorAll: vi.fn((selector) => {
+                if (selector !== '.news-list li')
+                    return [];
+                return [
+                    {
+                        querySelector: vi.fn((cardSelector) => {
+                            if (cardSelector === 'h3 a[href]') {
+                                return {
+                                    textContent: 'Article title',
+                                    getAttribute: vi.fn(() => '/link?url=abc'),
+                                };
+                            }
+                            if (cardSelector === 'p.txt-info')
+                                return { textContent: 'Summary' };
+                            if (cardSelector === '.s-p .s2')
+                                return { textContent: '2小时前' };
+                            return null;
+                        }),
+                    },
+                    {
+                        querySelector: vi.fn(() => null),
+                    },
+                ];
+            }),
+        };
+        const window = {
+            location: { origin: 'https://weixin.sogou.com' },
+            URL,
+        };
+        const script = __test__.buildExtractSearchResultsEvaluate();
+        const payload = Function('document', 'window', 'URL', `return ${script};`)(document, window, URL);
+
+        expect(payload).toMatchObject({
+            blocked: false,
+            empty: false,
+            cardCount: 2,
+            invalidCount: 1,
+            rows: [
+                {
+                    title: 'Article title',
+                    url: 'https://weixin.sogou.com/link?url=abc',
+                    summary: 'Summary',
+                    publish_time: '2小时前',
+                },
+            ],
+        });
+    });
+
+    it('exposes pure normalizers for direct regression coverage', () => {
+        expect(__test__.normalizePage(undefined)).toBe(1);
+        expect(__test__.normalizeLimit(undefined)).toBe(10);
+        expect(__test__.normalizeLimit(10)).toBe(10);
+        expect(() => __test__.normalizeLimit(11)).toThrow(/out of range/);
+        expect(__test__.buildSearchUrl('AI tools', 2)).toBe('https://weixin.sogou.com/weixin?query=AI+tools&type=2&page=2&ie=utf8');
+    });
+});

package/clis/wikidata/entity.js

@@ -0,0 +1,60 @@
+// wikidata entity — fetch a single Wikidata entity by Q/P/L identifier.
+//
+// Hits `Special:EntityData/<id>.json`, the canonical public dump. Surfaces the
+// agent-useful projection: localised label/description/aliases plus high-level
+// counts (claim properties, sitelinks). The full claim graph is huge; we keep
+// the projection narrow by design.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { WIKIDATA_BASE, joinAliases, pickLocalised, requireEntityId, requireLanguage, wikidataFetch } from './utils.js';
+
+cli({
+    site: 'wikidata',
+    name: 'entity',
+    access: 'read',
+    description: 'Fetch a Wikidata entity by Q/P/L id (label, description, aliases, claim summary)',
+    domain: 'www.wikidata.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Entity id (e.g. Q937 = Albert Einstein, P31 = instance of)' },
+        { name: 'language', default: 'en', help: 'Display language (ISO 639, falls back to English when missing)' },
+    ],
+    columns: [
+        'qid',
+        'type',
+        'label',
+        'description',
+        'aliases',
+        'claimPropertyCount',
+        'sitelinkCount',
+        'enwikiTitle',
+        'modified',
+        'url',
+    ],
+    func: async (args) => {
+        const qid = requireEntityId(args.id);
+        const language = requireLanguage(args.language);
+        const url = `${WIKIDATA_BASE}/wiki/Special:EntityData/${encodeURIComponent(qid)}.json`;
+        const body = await wikidataFetch(url, 'wikidata entity');
+        const entity = body?.entities?.[qid];
+        if (!entity) {
+            throw new EmptyResultError('wikidata entity', `Wikidata entity ${qid} returned no payload.`);
+        }
+        const claims = entity.claims && typeof entity.claims === 'object' ? entity.claims : {};
+        const sitelinks = entity.sitelinks && typeof entity.sitelinks === 'object' ? entity.sitelinks : {};
+        const enwiki = sitelinks?.enwiki?.title;
+        return [{
+            qid,
+            type: typeof entity.type === 'string' ? entity.type : null,
+            label: pickLocalised(entity.labels, language),
+            description: pickLocalised(entity.descriptions, language),
+            aliases: joinAliases(entity.aliases, language),
+            claimPropertyCount: Object.keys(claims).length,
+            sitelinkCount: Object.keys(sitelinks).length,
+            enwikiTitle: typeof enwiki === 'string' && enwiki.trim() ? enwiki : null,
+            modified: typeof entity.modified === 'string' ? entity.modified : null,
+            url: `${WIKIDATA_BASE}/wiki/${qid}`,
+        }];
+    },
+});

package/clis/wikidata/search.js

@@ -0,0 +1,50 @@
+// wikidata search — find Wikidata entities (items) by keyword.
+//
+// Hits `wbsearchentities` on the public MediaWiki API. Returns Q-IDs that
+// round-trip into `wikidata entity` for full detail.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { WIKIDATA_BASE, requireBoundedInt, requireLanguage, requireString, wikidataFetch } from './utils.js';
+
+cli({
+    site: 'wikidata',
+    name: 'search',
+    access: 'read',
+    description: 'Search Wikidata items by keyword (returns Q-IDs)',
+    domain: 'www.wikidata.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (label / alias)' },
+        { name: 'language', default: 'en', help: 'Search & display language (ISO 639, e.g. en, fr, zh)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max items (1-50)' },
+    ],
+    columns: ['rank', 'qid', 'label', 'description', 'matchType', 'matchText', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const language = requireLanguage(args.language);
+        const limit = requireBoundedInt(args.limit, 20, 50);
+        const url = `${WIKIDATA_BASE}/w/api.php?action=wbsearchentities`
+            + `&search=${encodeURIComponent(query)}`
+            + `&language=${encodeURIComponent(language)}`
+            + `&uselang=${encodeURIComponent(language)}`
+            + `&type=item&format=json&limit=${limit}&origin=*`;
+        const body = await wikidataFetch(url, 'wikidata search');
+        const list = Array.isArray(body?.search) ? body.search : [];
+        if (!list.length) {
+            throw new EmptyResultError('wikidata search', `No Wikidata items matched "${query}" in language "${language}".`);
+        }
+        return list.slice(0, limit).map((item, i) => {
+            const qid = String(item?.id ?? '').trim();
+            return {
+                rank: i + 1,
+                qid,
+                label: typeof item?.label === 'string' ? item.label : null,
+                description: typeof item?.description === 'string' ? item.description : null,
+                matchType: typeof item?.match?.type === 'string' ? item.match.type : null,
+                matchText: typeof item?.match?.text === 'string' ? item.match.text : null,
+                url: qid ? `${WIKIDATA_BASE}/wiki/${qid}` : '',
+            };
+        });
+    },
+});

package/clis/wikidata/utils.js

@@ -0,0 +1,117 @@
+// Shared helpers for the Wikidata adapters.
+//
+// Wikidata exposes two complementary public endpoints:
+//   • `wbsearchentities` on `www.wikidata.org/w/api.php` for keyword → Q-IDs
+//   • `Special:EntityData/<qid>.json` for the canonical entity dump
+// No API key. Anonymous traffic is rate-limited but generous; we set a polite UA.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const WIKIDATA_BASE = 'https://www.wikidata.org';
+const UA = 'opencli-wikidata-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';
+
+// Q-ID = an item; P-ID = a property; L-ID = a lexeme. We accept all three so the
+// adapter can be reused for properties / lexemes without a separate command, but
+// search only returns Q-IDs by default.
+const ENTITY_ID_PATTERN = /^[QPL]\d+$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`wikidata ${label} cannot be empty`);
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`wikidata ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`wikidata ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireEntityId(value) {
+    const raw = String(value ?? '').trim().toUpperCase();
+    if (!raw) throw new ArgumentError('wikidata entity id is required (e.g. "Q937")');
+    // Tolerate URL-paste like `https://www.wikidata.org/wiki/Q937`.
+    const stripped = raw.replace(/^HTTPS?:\/\/[^/]+\/WIKI\//i, '');
+    if (!ENTITY_ID_PATTERN.test(stripped)) {
+        throw new ArgumentError(
+            `wikidata entity id "${value}" is not a valid Q/P/L identifier`,
+            'Expected format: "Q<digits>" (item), "P<digits>" (property), or "L<digits>" (lexeme).',
+        );
+    }
+    return stripped;
+}
+
+export function requireLanguage(value, defaultValue = 'en') {
+    const raw = String(value ?? defaultValue).trim().toLowerCase();
+    // Wikidata language codes are 2-3 letter ISO 639 codes plus optional region (`zh-hans`).
+    if (!/^[a-z]{2,3}(-[a-z]{2,8})?$/.test(raw)) {
+        throw new ArgumentError(
+            `wikidata language "${value}" is not a valid language code`,
+            'Expected an ISO 639 language code such as "en", "fr", "zh", "zh-hans".',
+        );
+    }
+    return raw;
+}
+
+export async function wikidataFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that www.wikidata.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Wikidata returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Wikidata throttles anonymous traffic; back off and retry.',
+        );
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+/**
+ * Pick a localised label / description from a `{<lang>: {value}}` map.
+ * Falls back to English if the requested language is missing.
+ */
+export function pickLocalised(map, language) {
+    if (!map || typeof map !== 'object') return null;
+    const direct = map[language];
+    if (direct && typeof direct.value === 'string' && direct.value.trim()) return direct.value;
+    if (language !== 'en' && map.en && typeof map.en.value === 'string' && map.en.value.trim()) {
+        return map.en.value;
+    }
+    return null;
+}
+
+export function joinAliases(aliases, language, max = 5) {
+    if (!aliases || typeof aliases !== 'object') return '';
+    // Mirror the label/description fallback: prefer requested language, then English.
+    let list = Array.isArray(aliases[language]) ? aliases[language] : [];
+    if (list.length === 0 && language !== 'en' && Array.isArray(aliases.en)) list = aliases.en;
+    const names = list.map((a) => (a && typeof a.value === 'string' ? a.value : '')).filter(Boolean);
+    if (names.length === 0) return '';
+    if (names.length > max) return [...names.slice(0, max), `(+${names.length - max})`].join(', ');
+    return names.join(', ');
+}

package/clis/wikidata/wikidata.test.js

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './search.js';
+import './entity.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('wikidata search adapter', () => {
+    const cmd = getRegistry().get('wikidata/search');
+
+    it('rejects bad args before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ query: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ query: 'foo', limit: 999 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ query: 'foo', language: '!!' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('throttled', { status: 429 })));
+        await expect(cmd.func({ query: 'einstein', limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError on empty search list', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({ search: [] }), { status: 200 })));
+        await expect(cmd.func({ query: 'no-such-thing', limit: 5 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('round-trips Q-id from search row into wikidata.org URL', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            search: [{ id: 'Q937', label: 'Albert Einstein', description: 'physicist', match: { type: 'alias', text: 'Einstein' } }],
+        }), { status: 200 })));
+        const rows = await cmd.func({ query: 'einstein', limit: 5 });
+        expect(rows[0]).toMatchObject({
+            rank: 1, qid: 'Q937', label: 'Albert Einstein', matchType: 'alias',
+            url: 'https://www.wikidata.org/wiki/Q937',
+        });
+    });
+});
+
+describe('wikidata entity adapter', () => {
+    const cmd = getRegistry().get('wikidata/entity');
+
+    it('rejects malformed entity ids before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ id: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ id: 'not-a-qid' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ id: 'Q' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 404 to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('missing', { status: 404 })));
+        await expect(cmd.func({ id: 'Q9999999999' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('falls back to English label when requested language is missing', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            entities: {
+                Q937: {
+                    id: 'Q937', type: 'item', modified: '2026-01-01T00:00:00Z',
+                    labels: { en: { value: 'Albert Einstein', language: 'en' } },
+                    descriptions: { en: { value: 'physicist', language: 'en' } },
+                    aliases: { en: [{ value: 'A. Einstein', language: 'en' }] },
+                    claims: { P31: [], P21: [] },
+                    sitelinks: { enwiki: { title: 'Albert Einstein', site: 'enwiki' } },
+                },
+            },
+        }), { status: 200 })));
+        const rows = await cmd.func({ id: 'Q937', language: 'qq' });
+        expect(rows[0]).toMatchObject({
+            qid: 'Q937', label: 'Albert Einstein', description: 'physicist',
+            aliases: 'A. Einstein', claimPropertyCount: 2, sitelinkCount: 1,
+            enwikiTitle: 'Albert Einstein', url: 'https://www.wikidata.org/wiki/Q937',
+        });
+    });
+});

package/clis/wikipedia/page.js

@@ -0,0 +1,95 @@
+// wikipedia page — full article extract (plain text) with optional paragraph cap.
+//
+// Unlike `wikipedia summary` which returns the lead-section blurb truncated to
+// 300 chars, this adapter returns the *complete* article body (or the first N
+// paragraphs by explicit opt-in). No silent truncation: the caller decides.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+cli({
+    site: 'wikipedia',
+    name: 'page',
+    access: 'read',
+    description: 'Full plain-text extract of a Wikipedia article (optional paragraph cap).',
+    domain: 'wikipedia.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'title', positional: true, required: true, type: 'string', help: 'Article title (e.g. "Transformer (machine learning model)")' },
+        { name: 'lang', type: 'string', default: 'en', help: 'Language code (en, zh, ja, de, ...).' },
+        { name: 'paragraphs', type: 'int', default: 0, help: 'Cap to first N paragraphs (0 = full article).' },
+    ],
+    columns: ['title', 'description', 'pageId', 'paragraphs', 'extract', 'url'],
+    func: async (args) => {
+        const title = String(args.title ?? '').trim();
+        if (!title) {
+            throw new ArgumentError('wikipedia page title cannot be empty');
+        }
+        const lang = String(args.lang ?? 'en').trim().toLowerCase();
+        if (!/^[a-z]{2,3}(?:-[a-z0-9]+)?$/.test(lang)) {
+            throw new ArgumentError(`wikipedia lang must be a language code like en, zh, ja (got "${args.lang}")`);
+        }
+        const paragraphsCap = Number(args.paragraphs ?? 0);
+        if (!Number.isInteger(paragraphsCap) || paragraphsCap < 0) {
+            throw new ArgumentError('paragraphs must be a non-negative integer (0 = full article)');
+        }
+
+        const url = new URL(`https://${lang}.wikipedia.org/w/api.php`);
+        url.searchParams.set('action', 'query');
+        url.searchParams.set('format', 'json');
+        url.searchParams.set('formatversion', '2');
+        url.searchParams.set('prop', 'extracts|info|description');
+        url.searchParams.set('inprop', 'url');
+        url.searchParams.set('explaintext', '1');
+        url.searchParams.set('redirects', '1');
+        url.searchParams.set('titles', title);
+
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: {
+                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
+                    'Accept': 'application/json',
+                },
+            });
+        } catch (error) {
+            throw new CommandExecutionError(`wikipedia page request failed: ${error?.message || error}`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`wikipedia page failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`wikipedia returned malformed JSON: ${error?.message || error}`);
+        }
+        if (data?.error) {
+            throw new CommandExecutionError(`wikipedia API error: ${data.error.info || data.error.code}`);
+        }
+        const pages = Array.isArray(data?.query?.pages) ? data.query.pages : [];
+        const page = pages[0];
+        if (!page || page.missing) {
+            throw new EmptyResultError('wikipedia page', `No article "${title}" on ${lang}.wikipedia.org. Try \`opencli wikipedia search\` first.`);
+        }
+        const fullExtract = String(page.extract ?? '');
+        if (!fullExtract.trim()) {
+            throw new EmptyResultError('wikipedia page', `Article "${page.title}" exists but has no plain-text extract (likely a disambiguation/redirect page).`);
+        }
+        const allParas = fullExtract.split(/\n{2,}/).map(s => s.trim()).filter(Boolean);
+        const paras = paragraphsCap > 0 ? allParas.slice(0, paragraphsCap) : allParas;
+
+        return [{
+            title: page.title,
+            description: page.description || '',
+            pageId: page.pageid ?? null,
+            paragraphs: paras.length,
+            extract: paras.join('\n\n'),
+            url: page.fullurl || `https://${lang}.wikipedia.org/wiki/${encodeURIComponent(page.title.replace(/ /g, '_'))}`,
+        }];
+    },
+});