@jackwener/opencli 1.7.22 → 1.8.1

package/clis/weread-official/utils.js

@@ -0,0 +1,293 @@
+/**
+ * WeRead Official Agent Gateway helpers.
+ *
+ * Auth model: Bearer API key (WEREAD_API_KEY env var, format `wrk-*`).
+ * Transport:  pure HTTP, no browser required. Body shape must keep every
+ *             business parameter flat alongside `api_name` and `skill_version`
+ *             (wrapping them in `params`/`data`/`body` silently breaks the
+ *             gateway — see SKILL.md "请求 few-shot").
+ *
+ * This module is intentionally side-effect free outside `callGateway` so each
+ * command file can import only the helpers it needs.
+ */
+import {
+    ArgumentError,
+    AuthRequiredError,
+    CommandExecutionError,
+    EmptyResultError,
+    TimeoutError,
+} from '@jackwener/opencli/errors';
+
+export const WEREAD_GATEWAY_URL = 'https://i.weread.qq.com/api/agent/gateway';
+export const WEREAD_DOMAIN = 'weread.qq.com';
+
+/**
+ * Skill version reported with every gateway request. Bump when official
+ * `weread-skills.zip` ships a new SKILL.md `version:` line.
+ */
+export const SKILL_VERSION = '1.0.3';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** errcodes that mean "Bearer key invalid / token expired" — map to AuthRequiredError. */
+const AUTH_ERRCODES = new Set([-2010, -2012]);
+
+/** Resolve API key from env. Throws AuthRequiredError on missing / blank value. */
+export function getApiKey() {
+    const key = String(process.env.WEREAD_API_KEY ?? '').trim();
+    if (!key) {
+        throw new AuthRequiredError(
+            WEREAD_DOMAIN,
+            'WEREAD_API_KEY is not set. Export it with `export WEREAD_API_KEY=<wrk-...>`.',
+        );
+    }
+    return key;
+}
+
+/**
+ * Build the gateway request body. Business params are flattened next to
+ * `api_name` and `skill_version` — never wrapped in a `params` / `data` /
+ * `body` object (the gateway silently drops them and returns page 1).
+ */
+export function buildGatewayBody(apiName, params = {}) {
+    if (!apiName || typeof apiName !== 'string') {
+        throw new ArgumentError('weread-official: api_name is required');
+    }
+    const body = { api_name: apiName, skill_version: SKILL_VERSION };
+    for (const [key, value] of Object.entries(params ?? {})) {
+        if (value === undefined || value === null || value === '') continue;
+        body[key] = value;
+    }
+    return body;
+}
+
+/**
+ * POST to the agent gateway. Returns the parsed JSON payload on success.
+ * Maps every documented failure mode to a typed CliError:
+ *   - missing env key            → AuthRequiredError
+ *   - HTTP non-2xx               → CommandExecutionError
+ *   - network timeout            → TimeoutError
+ *   - response includes upgrade_info → CommandExecutionError (with version hint)
+ *   - errcode in AUTH_ERRCODES   → AuthRequiredError (Bearer key likely revoked)
+ *   - errcode != 0               → CommandExecutionError
+ */
+export async function callGateway(apiName, params = {}, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    const key = getApiKey();
+    const body = buildGatewayBody(apiName, params);
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let response;
+    try {
+        response = await fetch(WEREAD_GATEWAY_URL, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${key}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (error?.name === 'AbortError') {
+            throw new TimeoutError(`weread-official ${apiName}`, Math.round(timeoutMs / 1000));
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(`weread-official ${apiName} request failed`, detail);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+
+    if (!response.ok) {
+        throw new CommandExecutionError(
+            `weread-official ${apiName} HTTP ${response.status}`,
+            'Check WeRead gateway availability and that WEREAD_API_KEY is still valid.',
+        );
+    }
+
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(`weread-official ${apiName} returned invalid JSON`, detail);
+    }
+
+    if (payload && typeof payload === 'object' && payload.upgrade_info) {
+        const info = payload.upgrade_info;
+        const required = info?.required_version ?? info?.version ?? 'unknown';
+        const message = info?.message ?? 'WeRead skill version is outdated';
+        throw new CommandExecutionError(
+            `WeRead skill 需升级: ${message}. Required skill_version=${required}, current=${SKILL_VERSION}`,
+            'Pull the latest weread-skills.zip and bump SKILL_VERSION in clis/weread-official/utils.js.',
+        );
+    }
+
+    const errcode = Number(payload?.errcode ?? 0);
+    if (errcode !== 0) {
+        const errmsg = String(payload?.errmsg ?? 'unknown error');
+        if (AUTH_ERRCODES.has(errcode)) {
+            throw new AuthRequiredError(
+                WEREAD_DOMAIN,
+                `WEREAD_API_KEY rejected (errcode=${errcode}, ${errmsg}). Regenerate the key and re-export it.`,
+            );
+        }
+        throw new CommandExecutionError(
+            `weread-official ${apiName} returned errcode=${errcode}`,
+            errmsg,
+        );
+    }
+
+    return payload;
+}
+
+// ── Formatting helpers ──────────────────────────────────────────────────────
+
+/** Unix timestamp (sec) → YYYY-MM-DD using UTC for stable test snapshots. */
+export function formatDate(ts) {
+    const seconds = Number(ts);
+    if (!Number.isFinite(seconds) || seconds <= 0) return '';
+    const date = new Date(seconds * 1000);
+    if (Number.isNaN(date.getTime())) return '';
+    const y = date.getUTCFullYear();
+    const m = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const d = String(date.getUTCDate()).padStart(2, '0');
+    return `${y}-${m}-${d}`;
+}
+
+/** Seconds → "X小时Y分钟" (or "Y分钟" if no hours, "0分钟" if < 1 minute). */
+export function formatDuration(secs) {
+    if (secs === null || secs === undefined || secs === '') return '';
+    const total = Number(secs);
+    if (!Number.isFinite(total) || total < 0) return '';
+    const seconds = Math.floor(total);
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    if (hours > 0) return `${hours}小时${minutes}分钟`;
+    return `${minutes}分钟`;
+}
+
+/**
+ * WeRead `star` field uses multiples of 20 (20=1⭐, 40=2⭐, …, 100=5⭐).
+ * `-1` and `0` both mean "no rating".
+ */
+export function formatStar(star) {
+    const value = Number(star);
+    if (!Number.isFinite(value) || value <= 0) return '无评分';
+    const count = Math.min(5, Math.floor(value / 20));
+    if (count <= 0) return '无评分';
+    return '⭐'.repeat(count);
+}
+
+/**
+ * WeRead book rating uses a 0-1000 scale (1000 = 100%). Returns a short label
+ * with the canonical tier names from the official skill output examples.
+ */
+export function formatRating(rating) {
+    const value = Number(rating);
+    if (!Number.isFinite(value) || value <= 0) return '暂无';
+    const percent = value / 10;
+    if (percent >= 90) return `神作 ${Math.round(percent)}%`;
+    if (percent >= 80) return `力荐 ${Math.round(percent)}%`;
+    if (percent >= 70) return `好评 ${Math.round(percent)}%`;
+    return `${percent.toFixed(1)}分`;
+}
+
+/** Truncate text to `maxLen` chars with an ellipsis suffix. Returns '' for nullish. */
+export function truncate(text, maxLen = 200) {
+    const value = String(text ?? '');
+    if (!value) return '';
+    if (value.length <= maxLen) return value;
+    return `${value.slice(0, maxLen)}…`;
+}
+
+// ── Deep links ──────────────────────────────────────────────────────────────
+
+/**
+ * Build a `weread://` deep link.
+ *  - bookId only                                 → open at last reading position
+ *  - bookId + chapterUid                         → open chapter
+ *  - bookId + chapterUid + rangeStart + rangeEnd → open bestbookmark position
+ */
+export function makeDeepLink({ bookId, chapterUid = '', rangeStart = '', rangeEnd = '', userVid = '' } = {}) {
+    const bid = String(bookId ?? '').trim();
+    if (!bid) return '';
+    const chapter = String(chapterUid ?? '').trim();
+    const start = String(rangeStart ?? '').trim();
+    const end = String(rangeEnd ?? '').trim();
+    if (chapter && start && end) {
+        const params = new URLSearchParams({ bookId: bid, chapterUid: chapter, rangeStart: start, rangeEnd: end });
+        const vid = String(userVid ?? '').trim();
+        if (vid) params.set('userVid', vid);
+        return `weread://bestbookmark?${params.toString()}`;
+    }
+    if (chapter) return `weread://reading?bId=${bid}&chapterUid=${chapter}`;
+    return `weread://reading?bId=${bid}`;
+}
+
+/**
+ * Split a WeRead `range` field ("900-2004") into `{rangeStart, rangeEnd}`.
+ * Returns empty strings when the input is missing/malformed.
+ */
+export function parseRange(range) {
+    const text = String(range ?? '').trim();
+    const match = text.match(/^(\d+)-(\d+)$/);
+    if (!match) return { rangeStart: '', rangeEnd: '' };
+    return { rangeStart: match[1], rangeEnd: match[2] };
+}
+
+// ── Argument validation ─────────────────────────────────────────────────────
+
+export function requireText(value, label) {
+    const text = String(value ?? '').trim();
+    if (!text) throw new ArgumentError(`weread-official: ${label} cannot be empty`);
+    return text;
+}
+
+export function requireBookId(value, label = 'bookId') {
+    const text = requireText(value, label);
+    if (!/^[A-Za-z0-9_-]+$/.test(text)) {
+        throw new ArgumentError(`weread-official: ${label} contains invalid characters`, 'Pass a bookId from `weread-official search`.');
+    }
+    return text;
+}
+
+export function requirePositiveInt(value, label, { defaultValue, max } = {}) {
+    if (value === undefined || value === null || value === '') {
+        if (defaultValue === undefined) {
+            throw new ArgumentError(`weread-official: ${label} is required`);
+        }
+        return defaultValue;
+    }
+    const text = String(value).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new ArgumentError(`weread-official: ${label} must be a positive integer`);
+    }
+    const n = Number(text);
+    if (!Number.isSafeInteger(n) || n < 1) {
+        throw new ArgumentError(`weread-official: ${label} must be a positive integer`);
+    }
+    if (max !== undefined && n > max) {
+        throw new ArgumentError(`weread-official: ${label} must be <= ${max}`);
+    }
+    return n;
+}
+
+export function requireChoice(value, choices, label, defaultValue) {
+    const text = String(value ?? defaultValue ?? '').trim();
+    if (!choices.includes(text)) {
+        throw new ArgumentError(`weread-official: ${label} must be one of: ${choices.join(', ')}`);
+    }
+    return text;
+}
+
+// ── Empty-result helper ────────────────────────────────────────────────────
+
+/** Throw EmptyResultError with a stable command label. */
+export function emptyResult(command, hint) {
+    throw new EmptyResultError(`weread-official ${command}`, hint);
+}

package/clis/weread-official/utils.test.js

@@ -0,0 +1,242 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+    ArgumentError,
+    AuthRequiredError,
+    CommandExecutionError,
+    EmptyResultError,
+    TimeoutError,
+} from '@jackwener/opencli/errors';
+import {
+    SKILL_VERSION,
+    WEREAD_GATEWAY_URL,
+    buildGatewayBody,
+    callGateway,
+    emptyResult,
+    formatDate,
+    formatDuration,
+    formatRating,
+    formatStar,
+    getApiKey,
+    makeDeepLink,
+    parseRange,
+    requireBookId,
+    requireChoice,
+    requirePositiveInt,
+    requireText,
+    truncate,
+} from './utils.js';
+
+function jsonResponse(body, ok = true, status = 200) {
+    return {
+        ok,
+        status,
+        json: vi.fn().mockResolvedValue(body),
+        text: vi.fn().mockResolvedValue(JSON.stringify(body)),
+    };
+}
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+});
+
+describe('weread-official utils — formatting', () => {
+    it('formats Unix timestamps as YYYY-MM-DD (UTC) and falls back to empty', () => {
+        expect(formatDate(1748563200)).toBe('2025-05-30');
+        expect(formatDate(0)).toBe('');
+        expect(formatDate(null)).toBe('');
+        expect(formatDate('not-a-number')).toBe('');
+    });
+
+    it('formats duration seconds into "X小时Y分钟" / "Y分钟"', () => {
+        expect(formatDuration(3600)).toBe('1小时0分钟');
+        expect(formatDuration(3660)).toBe('1小时1分钟');
+        expect(formatDuration(59)).toBe('0分钟');
+        expect(formatDuration(0)).toBe('0分钟');
+        expect(formatDuration(-1)).toBe('');
+        expect(formatDuration(null)).toBe('');
+    });
+
+    it('translates star multiples-of-20 into ⭐ glyphs (caps at 5)', () => {
+        expect(formatStar(20)).toBe('⭐');
+        expect(formatStar(80)).toBe('⭐⭐⭐⭐');
+        expect(formatStar(100)).toBe('⭐⭐⭐⭐⭐');
+        expect(formatStar(120)).toBe('⭐⭐⭐⭐⭐');
+        expect(formatStar(0)).toBe('无评分');
+        expect(formatStar(-1)).toBe('无评分');
+    });
+
+    it('labels ratings by the official 0-1000 tiers', () => {
+        expect(formatRating(950)).toMatch(/^神作 95%$/);
+        expect(formatRating(820)).toMatch(/^力荐 82%$/);
+        expect(formatRating(710)).toMatch(/^好评 71%$/);
+        expect(formatRating(550)).toBe('55.0分');
+        expect(formatRating(0)).toBe('暂无');
+        expect(formatRating(null)).toBe('暂无');
+    });
+
+    it('truncates text with an ellipsis suffix and tolerates nullish input', () => {
+        expect(truncate('hello', 100)).toBe('hello');
+        expect(truncate('1234567890', 5)).toBe('12345…');
+        expect(truncate(null, 5)).toBe('');
+        expect(truncate(undefined, 5)).toBe('');
+    });
+});
+
+describe('weread-official utils — deep links', () => {
+    it('builds book-level, chapter-level, and bestbookmark URLs', () => {
+        expect(makeDeepLink({ bookId: '3300045871' })).toBe('weread://reading?bId=3300045871');
+        expect(makeDeepLink({ bookId: '3300045871', chapterUid: '107' })).toBe('weread://reading?bId=3300045871&chapterUid=107');
+        expect(makeDeepLink({ bookId: '3300045871', chapterUid: '107', rangeStart: '900', rangeEnd: '2004' }))
+            .toBe('weread://bestbookmark?bookId=3300045871&chapterUid=107&rangeStart=900&rangeEnd=2004');
+        expect(makeDeepLink({ bookId: '3300045871', chapterUid: '107', rangeStart: '900', rangeEnd: '2004', userVid: '583802764' }))
+            .toBe('weread://bestbookmark?bookId=3300045871&chapterUid=107&rangeStart=900&rangeEnd=2004&userVid=583802764');
+        expect(makeDeepLink({})).toBe('');
+        expect(makeDeepLink({ bookId: '' })).toBe('');
+    });
+
+    it('parses ranges like "900-2004" and returns empty on malformed input', () => {
+        expect(parseRange('900-2004')).toEqual({ rangeStart: '900', rangeEnd: '2004' });
+        expect(parseRange('garbage')).toEqual({ rangeStart: '', rangeEnd: '' });
+        expect(parseRange('')).toEqual({ rangeStart: '', rangeEnd: '' });
+        expect(parseRange(null)).toEqual({ rangeStart: '', rangeEnd: '' });
+    });
+});
+
+describe('weread-official utils — argument validation', () => {
+    it('rejects empty text and blank bookIds', () => {
+        expect(requireText('hello', 'q')).toBe('hello');
+        expect(() => requireText('', 'q')).toThrow(ArgumentError);
+        expect(() => requireText('   ', 'q')).toThrow(ArgumentError);
+        expect(requireBookId('book_123-AbC')).toBe('book_123-AbC');
+        expect(() => requireBookId('')).toThrow(ArgumentError);
+        expect(() => requireBookId('book id with space')).toThrow(ArgumentError);
+    });
+
+    it('enforces positive integers with optional default and max', () => {
+        expect(requirePositiveInt(undefined, 'n', { defaultValue: 10 })).toBe(10);
+        expect(requirePositiveInt('15', 'n')).toBe(15);
+        expect(() => requirePositiveInt('0', 'n')).toThrow(ArgumentError);
+        expect(() => requirePositiveInt('-3', 'n')).toThrow(ArgumentError);
+        expect(() => requirePositiveInt('abc', 'n')).toThrow(ArgumentError);
+        expect(() => requirePositiveInt('200', 'n', { max: 100 })).toThrow(/<= 100/);
+    });
+
+    it('requireChoice rejects values outside the allowlist', () => {
+        expect(requireChoice('weekly', ['weekly', 'monthly'], 'mode', 'monthly')).toBe('weekly');
+        expect(requireChoice(undefined, ['weekly', 'monthly'], 'mode', 'monthly')).toBe('monthly');
+        expect(() => requireChoice('quarterly', ['weekly', 'monthly'], 'mode', 'monthly')).toThrow(ArgumentError);
+    });
+});
+
+describe('weread-official utils — request building', () => {
+    it('flattens business params alongside api_name + skill_version', () => {
+        const body = buildGatewayBody('/store/search', { keyword: '三体', scope: 10, maxIdx: 0 });
+        expect(body.api_name).toBe('/store/search');
+        expect(body.skill_version).toBe(SKILL_VERSION);
+        expect(body.keyword).toBe('三体');
+        expect(body.scope).toBe(10);
+        // Empty values should be dropped so the gateway does not see empty strings.
+        const body2 = buildGatewayBody('/_list', { foo: '', bar: null, baz: undefined, keep: 'yes' });
+        expect(body2).not.toHaveProperty('foo');
+        expect(body2).not.toHaveProperty('bar');
+        expect(body2).not.toHaveProperty('baz');
+        expect(body2.keep).toBe('yes');
+    });
+
+    it('rejects empty api_name', () => {
+        expect(() => buildGatewayBody('', {})).toThrow(ArgumentError);
+        expect(() => buildGatewayBody(null, {})).toThrow(ArgumentError);
+    });
+});
+
+describe('weread-official utils — auth and callGateway', () => {
+    it('throws AuthRequiredError when WEREAD_API_KEY env var is missing', () => {
+        vi.stubEnv('WEREAD_API_KEY', '');
+        expect(() => getApiKey()).toThrow(AuthRequiredError);
+    });
+
+    it('reads and trims WEREAD_API_KEY from env', () => {
+        vi.stubEnv('WEREAD_API_KEY', '  wrk-abc  ');
+        expect(getApiKey()).toBe('wrk-abc');
+    });
+
+    it('posts with Bearer auth and JSON body to the gateway URL', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ errcode: 0, ok: 1 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const result = await callGateway('/store/search', { keyword: '三体', scope: 10 });
+        expect(result).toEqual({ errcode: 0, ok: 1 });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe(WEREAD_GATEWAY_URL);
+        expect(init.method).toBe('POST');
+        expect(init.headers.Authorization).toBe('Bearer wrk-test');
+        expect(init.headers['Content-Type']).toBe('application/json');
+        const parsed = JSON.parse(init.body);
+        expect(parsed.api_name).toBe('/store/search');
+        expect(parsed.skill_version).toBe(SKILL_VERSION);
+        expect(parsed.keyword).toBe('三体');
+    });
+
+    it('maps upgrade_info responses into CommandExecutionError naming both versions', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            upgrade_info: { message: '请升级 skill', required_version: '99.9.9' },
+            errcode: 0,
+        })));
+        await expect(callGateway('/_list', {})).rejects.toThrow(/Required skill_version=99\.9\.9/);
+        await expect(callGateway('/_list', {})).rejects.toThrow(/current=/);
+    });
+
+    it('maps Bearer-key reject errcodes into AuthRequiredError', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ errcode: -2010, errmsg: 'token expired' })));
+        await expect(callGateway('/shelf/sync', {})).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('maps non-zero non-auth errcodes into CommandExecutionError', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ errcode: 7, errmsg: 'oops' })));
+        await expect(callGateway('/shelf/sync', {})).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps HTTP non-2xx into CommandExecutionError', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({}, false, 500)));
+        await expect(callGateway('/shelf/sync', {})).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps abort signals into TimeoutError', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(Object.assign(new Error('aborted'), { name: 'AbortError' })));
+        await expect(callGateway('/shelf/sync', {})).rejects.toBeInstanceOf(TimeoutError);
+    });
+
+    it('maps generic fetch errors into CommandExecutionError', async () => {
+        vi.stubEnv('WEREAD_API_KEY', 'wrk-test');
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('socket hang up')));
+        await expect(callGateway('/shelf/sync', {})).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('refuses to call the gateway without an API key', async () => {
+        vi.stubEnv('WEREAD_API_KEY', '');
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(callGateway('/shelf/sync', {})).rejects.toBeInstanceOf(AuthRequiredError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+});
+
+describe('weread-official utils — empty-result helper', () => {
+    it('throws EmptyResultError with the canonical command label', () => {
+        try {
+            emptyResult('search', 'No hits');
+            expect.unreachable('emptyResult should have thrown');
+        }
+        catch (error) {
+            expect(error).toBeInstanceOf(EmptyResultError);
+            expect(error.message).toContain('weread-official search');
+        }
+    });
+});

package/clis/wikipedia/trending.js

@@ -26,10 +26,14 @@ cli({
         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) => ({
+        const selectedArticles = articles.slice(0, limit);
+        if (selectedArticles.some((article) => !String(article?.title || '').trim())) {
+            throw new CliError('PARSE_ERROR', 'Wikipedia trending returned an article without title', 'Trending rows require a title so they can be opened with wikipedia page.');
+        }
+        return selectedArticles.map((a, i) => ({
             rank: i + 1,
-            title: a.title ?? '-',
-            description: (a.description ?? '-').slice(0, DESC_MAX_LEN),
+            title: a.title,
+            description: (a.description ?? '').slice(0, DESC_MAX_LEN),
             views: a.views ?? 0,
         }));
     },

package/clis/wikipedia/trending.test.js

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+
+const { wikiFetchMock } = vi.hoisted(() => ({ wikiFetchMock: vi.fn() }));
+vi.mock('./utils.js', async () => {
+    const actual = await vi.importActual('./utils.js');
+    return { ...actual, wikiFetch: wikiFetchMock };
+});
+
+import './trending.js';
+
+describe('wikipedia trending', () => {
+    beforeEach(() => {
+        wikiFetchMock.mockReset();
+    });
+
+    it('emits empty-string for missing description instead of a sentinel', async () => {
+        const command = getRegistry().get('wikipedia/trending');
+        expect(command?.func).toBeDefined();
+        wikiFetchMock.mockResolvedValueOnce({
+            mostread: {
+                articles: [
+                    { title: 'Has_Both', description: 'A real description', views: 100 },
+                    { title: 'Has_Title_Only', views: 25 },
+                ],
+            },
+        });
+        const rows = await command.func({ limit: 5, lang: 'en' });
+        expect(rows).toHaveLength(2);
+        expect(rows[0]).toMatchObject({ title: 'Has_Both', description: 'A real description', views: 100 });
+        expect(rows[1].title).toBe('Has_Title_Only');
+        expect(rows[1].description).toBe('');
+    });
+
+    it('fails typed when a trending article is missing title identity', async () => {
+        const command = getRegistry().get('wikipedia/trending');
+        wikiFetchMock.mockResolvedValueOnce({
+            mostread: { articles: [{ views: 50 }] },
+        });
+        await expect(command.func({ limit: 5, lang: 'en' })).rejects.toMatchObject({ code: 'PARSE_ERROR' });
+    });
+
+    it('validates only rows selected by --limit', async () => {
+        const command = getRegistry().get('wikipedia/trending');
+        wikiFetchMock.mockResolvedValueOnce({
+            mostread: {
+                articles: [
+                    { title: 'Selected', views: 100 },
+                    { views: 50 },
+                ],
+            },
+        });
+        await expect(command.func({ limit: 1, lang: 'en' })).resolves.toEqual([
+            { rank: 1, title: 'Selected', description: '', views: 100 },
+        ]);
+    });
+});