publishport-opencli 1.8.4-pp.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/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}` : '',
+            };
+        });
+    },
+});