publishport-opencli 1.8.4-pp.1

package/clis/semanticscholar/recommendations.js

@@ -0,0 +1,47 @@
+// semanticscholar recommendations: AI-curated related papers from Semantic
+// Scholar's semantic graph. This endpoint has no equivalent in openalex or
+// arxiv; it is the Semantic Scholar adapter's main differentiating surface.
+//
+// Hits `https://api.semanticscholar.org/recommendations/v1/papers/forpaper/{ref}`.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    S2_REC_BASE,
+    normalizePaperRow,
+    requireBoundedInt,
+    requirePaperRef,
+    s2Fetch,
+} from './utils.js';
+
+const FIELDS = ['paperId', 'title', 'year', 'authors', 'citationCount', 'externalIds'].join(',');
+
+cli({
+    site: 'semanticscholar',
+    name: 'recommendations',
+    access: 'read',
+    description: 'Semantic Scholar AI-curated related papers for a paperId, DOI, or arXiv id',
+    domain: 'api.semanticscholar.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'paperId (40-char hex), DOI, arXiv id, or prefixed id' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max recommendations (1-500)' },
+    ],
+    columns: ['rank', 'paperId', 'doi', 'title', 'year', 'firstAuthor', 'citationCount', 'url'],
+    func: async (args) => {
+        const ref = requirePaperRef(args.id);
+        const limit = requireBoundedInt(args.limit, 10, 500);
+        const url = `${S2_REC_BASE}/papers/forpaper/${encodeURIComponent(ref)}?fields=${FIELDS}&limit=${limit}`;
+        const body = await s2Fetch(url, 'semanticscholar recommendations');
+
+        const recommended = Array.isArray(body?.recommendedPapers) ? body.recommendedPapers : null;
+        if (recommended === null) {
+            throw new CommandExecutionError('semanticscholar recommendations returned an unexpected payload shape');
+        }
+        if (!recommended.length) {
+            throw new EmptyResultError('semanticscholar recommendations', `No Semantic Scholar recommendations for "${args.id}".`);
+        }
+
+        return recommended.slice(0, limit).map((p, i) => normalizePaperRow(p, 'recommendations', { rank: i + 1 }));
+    },
+});

package/clis/semanticscholar/search.js

@@ -0,0 +1,48 @@
+// semanticscholar search: paper search across the Semantic Scholar graph.
+//
+// Hits `/paper/search?query=...`. Returns the agent-useful projection:
+// paperId (round-trips into `semanticscholar paper`), DOI, title, year,
+// first author, citationCount. The bulk search endpoint is the rate-limited
+// surface, so `utils.s2Fetch` retries once on 429.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    S2_GRAPH_BASE,
+    normalizePaperRow,
+    requireBoundedInt,
+    requireString,
+    s2Fetch,
+} from './utils.js';
+
+const FIELDS = ['paperId', 'title', 'year', 'authors', 'citationCount', 'externalIds'].join(',');
+
+cli({
+    site: 'semanticscholar',
+    name: 'search',
+    access: 'read',
+    description: 'Search Semantic Scholar papers by free text',
+    domain: 'api.semanticscholar.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search text (e.g. "attention is all you need", "diffusion model")' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max papers (1-100, single Semantic Scholar page)' },
+    ],
+    columns: ['rank', 'paperId', 'doi', 'title', 'year', 'firstAuthor', 'citationCount', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 20, 100);
+        const url = `${S2_GRAPH_BASE}/paper/search?query=${encodeURIComponent(query)}&limit=${limit}&fields=${FIELDS}`;
+        const body = await s2Fetch(url, 'semanticscholar search');
+
+        const data = Array.isArray(body?.data) ? body.data : null;
+        if (data === null) {
+            throw new CommandExecutionError('semanticscholar search returned an unexpected payload shape');
+        }
+        if (!data.length) {
+            throw new EmptyResultError('semanticscholar search', `No Semantic Scholar papers matched "${query}".`);
+        }
+
+        return data.slice(0, limit).map((p, i) => normalizePaperRow(p, 'search', { rank: i + 1 }));
+    },
+});

package/clis/semanticscholar/semanticscholar.test.js

@@ -0,0 +1,279 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './paper.js';
+import './citations.js';
+import './recommendations.js';
+import './search.js';
+
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    delete process.env.SEMANTIC_SCHOLAR_API_KEY;
+});
+
+describe('semanticscholar adapter registry contracts', () => {
+    it('declares paper columns so paperId round-trips into citations and recommendations', () => {
+        const paper = getRegistry().get('semanticscholar/paper');
+        const citations = getRegistry().get('semanticscholar/citations');
+        const recommendations = getRegistry().get('semanticscholar/recommendations');
+
+        expect(paper).toBeDefined();
+        expect(citations).toBeDefined();
+        expect(recommendations).toBeDefined();
+        expect(paper.columns).toContain('paperId');
+        expect(citations.columns).toContain('paperId');
+        expect(recommendations.columns).toContain('paperId');
+    });
+
+    it('surfaces the unique Semantic Scholar fields on paper detail', () => {
+        const paper = getRegistry().get('semanticscholar/paper');
+
+        expect(paper.columns).toContain('influentialCitationCount');
+        expect(paper.columns).toContain('tldr');
+    });
+
+    it('marks every command as read access on the api.semanticscholar.org domain', () => {
+        for (const name of ['paper', 'citations', 'recommendations', 'search']) {
+            const cmd = getRegistry().get(`semanticscholar/${name}`);
+            expect(cmd, name).toBeDefined();
+            expect(cmd.access, name).toBe('read');
+            expect(cmd.domain, name).toBe('api.semanticscholar.org');
+            expect(cmd.browser, name).toBe(false);
+        }
+    });
+});
+
+describe('semanticscholar paper command', () => {
+    const command = getRegistry().get('semanticscholar/paper');
+
+    it('returns the paper row with citation graph and tldr', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
+            paperId: 'df2b0e26d0599ce3e70df8a9da02e51594e0e992',
+            title: 'BERT: Pre-training of Deep Bidirectional Transformers',
+            year: 2019,
+            authors: [{ name: 'Jacob Devlin' }, { name: 'Ming-Wei Chang' }],
+            citationCount: 116233,
+            influentialCitationCount: 22448,
+            referenceCount: 63,
+            tldr: { text: 'A new language representation model called BERT.' },
+            externalIds: { DOI: '10.18653/v1/N19-1423' },
+            url: 'https://www.semanticscholar.org/paper/df2b0e26d0599ce3e70df8a9da02e51594e0e992',
+        }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(command.func({ id: '10.18653/v1/N19-1423' })).resolves.toEqual([{
+            paperId: 'df2b0e26d0599ce3e70df8a9da02e51594e0e992',
+            doi: '10.18653/v1/N19-1423',
+            title: 'BERT: Pre-training of Deep Bidirectional Transformers',
+            year: 2019,
+            firstAuthor: 'Jacob Devlin',
+            citationCount: 116233,
+            influentialCitationCount: 22448,
+            referenceCount: 63,
+            tldr: 'A new language representation model called BERT.',
+            url: 'https://www.semanticscholar.org/paper/df2b0e26d0599ce3e70df8a9da02e51594e0e992',
+        }]);
+        // DOI normalization: bare 10.x DOIs get the DOI: prefix encoded into the path.
+        expect(fetchMock.mock.calls[0][0]).toContain('DOI%3A10.18653%2Fv1%2FN19-1423');
+    });
+
+    it('forwards SEMANTIC_SCHOLAR_API_KEY as the x-api-key header when set', async () => {
+        process.env.SEMANTIC_SCHOLAR_API_KEY = 'test-key';
+        const paperId = 'a'.repeat(40);
+        const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ paperId, title: 'x' }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        await command.func({ id: paperId });
+        expect(fetchMock.mock.calls[0][1].headers['x-api-key']).toBe('test-key');
+    });
+
+    it('rejects invalid identifiers before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(command.func({ id: '' })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func({ id: 'not a real reference' })).rejects.toBeInstanceOf(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('typed-fails malformed paper detail rows instead of treating parser drift as empty', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({})));
+
+        await expect(command.func({ id: '10.0/missing' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('typed-fails non-numeric metric fields instead of returning NaN', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            paperId: 'df2b0e26d0599ce3e70df8a9da02e51594e0e992',
+            title: 'Bad Metrics',
+            citationCount: 'many',
+        })));
+
+        await expect(command.func({ id: '10.0/bad-metrics' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});
+
+describe('semanticscholar citations command', () => {
+    const command = getRegistry().get('semanticscholar/citations');
+
+    it('unwraps citingPaper rows and offsets ranks correctly', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            data: [
+                { citingPaper: { paperId: 'p1', title: 'Citing One', year: 2024, authors: [{ name: 'Alice' }], citationCount: 5, externalIds: { DOI: '10.1/p1' } } },
+                { citingPaper: { paperId: 'p2', title: 'Citing Two', year: 2025, authors: [{ name: 'Bob' }], citationCount: 12, externalIds: {} } },
+            ],
+        })));
+
+        await expect(command.func({ id: '10.18653/v1/N19-1423', limit: 2, offset: 10 })).resolves.toEqual([
+            { rank: 11, paperId: 'p1', doi: '10.1/p1', title: 'Citing One', year: 2024, firstAuthor: 'Alice', citationCount: 5, url: 'https://www.semanticscholar.org/paper/p1' },
+            { rank: 12, paperId: 'p2', doi: '', title: 'Citing Two', year: 2025, firstAuthor: 'Bob', citationCount: 12, url: 'https://www.semanticscholar.org/paper/p2' },
+        ]);
+    });
+
+    it('rejects invalid arguments before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(command.func({ id: '', limit: 5 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func({ id: '10.0/x', limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func({ id: '10.0/x', limit: 1001 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps empty citation pages to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ data: [] })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('typed-fails malformed payloads instead of returning empty rows', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ wrong: 'shape' })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('typed-fails malformed citation rows without a citing paper identity', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            data: [{ citingPaper: { title: 'Missing identity' } }],
+        })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('typed-fails citation entries missing citingPaper instead of emitting blank rows', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            data: [{ contexts: ['missing citing paper'] }],
+        })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});
+
+describe('semanticscholar recommendations command', () => {
+    const command = getRegistry().get('semanticscholar/recommendations');
+
+    it('returns recommendedPapers rows ranked from 1', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            recommendedPapers: [
+                { paperId: 'r1', title: 'Related One', year: 2024, authors: [{ name: 'Carol' }], citationCount: 7, externalIds: { DOI: '10.1/r1' } },
+            ],
+        })));
+
+        await expect(command.func({ id: '10.18653/v1/N19-1423', limit: 1 })).resolves.toEqual([
+            { rank: 1, paperId: 'r1', doi: '10.1/r1', title: 'Related One', year: 2024, firstAuthor: 'Carol', citationCount: 7, url: 'https://www.semanticscholar.org/paper/r1' },
+        ]);
+    });
+
+    it('maps empty recommendation responses to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ recommendedPapers: [] })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('typed-fails when the payload is missing recommendedPapers entirely', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ wrong: 'shape' })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('typed-fails malformed recommendation rows without a stable paper identity', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            recommendedPapers: [{ title: 'Missing id' }],
+        })));
+
+        await expect(command.func({ id: '10.0/x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});
+
+describe('semanticscholar search command', () => {
+    const command = getRegistry().get('semanticscholar/search');
+
+    it('returns search rows that round-trip into semanticscholar paper', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
+            data: [{
+                paperId: 'sp1',
+                title: 'A Search Hit',
+                year: 2023,
+                authors: [{ name: 'Dana' }],
+                citationCount: 99,
+                externalIds: { DOI: '10.1/sp1' },
+            }],
+        }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(command.func({ query: 'transformers', limit: 1 })).resolves.toEqual([{
+            rank: 1,
+            paperId: 'sp1',
+            doi: '10.1/sp1',
+            title: 'A Search Hit',
+            year: 2023,
+            firstAuthor: 'Dana',
+            citationCount: 99,
+            url: 'https://www.semanticscholar.org/paper/sp1',
+        }]);
+        const url = new URL(fetchMock.mock.calls[0][0]);
+        expect(url.searchParams.get('query')).toBe('transformers');
+    });
+
+    it('rejects invalid arguments before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(command.func({ query: ' ', limit: 5 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func({ query: 'x', limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func({ query: 'x', limit: 101 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('retries once on 429 when no API key is configured', async () => {
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce(new Response('rate limited', { status: 429 }))
+            .mockResolvedValueOnce(jsonResponse({ data: [{ paperId: 'after', title: 'Recovered', year: 2024, authors: [], citationCount: 0, externalIds: {} }] }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const rows = await command.func({ query: 'bursty', limit: 1 });
+        expect(rows[0].paperId).toBe('after');
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('maps empty search results to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ data: [] })));
+
+        await expect(command.func({ query: 'zz-no-hit', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('typed-fails malformed search rows without a stable paper identity', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
+            data: [{ title: 'Missing id' }],
+        })));
+
+        await expect(command.func({ query: 'broken row', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});

package/clis/semanticscholar/utils.js

@@ -0,0 +1,196 @@
+// Shared helpers for the Semantic Scholar (`api.semanticscholar.org`) adapter.
+//
+// Semantic Scholar exposes a free Academic Graph + a separate Recommendations
+// API. Anonymous traffic caps at roughly 100 requests / 5 minutes; an optional
+// API key (free at https://www.semanticscholar.org/product/api#api-key-form)
+// lifts the limit and is passed via `SEMANTIC_SCHOLAR_API_KEY`. Paper refs
+// accept Semantic Scholar paperIds, DOIs, arXiv ids, ACL ids, MAG ids, PMID,
+// or full URLs; they round-trip through `paper <ref>` to `citations <ref>`
+// and `recommendations <ref>`.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const S2_GRAPH_BASE = 'https://api.semanticscholar.org/graph/v1';
+export const S2_REC_BASE = 'https://api.semanticscholar.org/recommendations/v1';
+const UA = 'opencli-semanticscholar-adapter (+https://github.com/jackwener/opencli)';
+
+// Semantic Scholar paperId: 40-char lowercase hex (SHA-ish).
+const S2_PAPER_ID = /^[0-9a-f]{40}$/i;
+// DOIs: anything starting with 10. after an optional `doi:` / `doi.org/` prefix.
+const DOI_BARE = /^10\.\S+$/;
+// arXiv ids: modern `YYMM.NNNNN` form or legacy `archive/YYMMNNN`.
+const ARXIV_MODERN = /^\d{4}\.\d{4,5}(?:v\d+)?$/;
+const ARXIV_LEGACY = /^[a-z-]+\/\d{7}(?:v\d+)?$/i;
+// Other Semantic Scholar accepted prefixes that we pass through verbatim.
+const PREFIXED = /^(ARXIV|MAG|ACL|PMID|PMCID|URL|CorpusId|DBLP):/i;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError(`semanticscholar ${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(`semanticscholar ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`semanticscholar ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+/**
+ * Resolve a user-supplied paper reference to a Semantic Scholar paper id
+ * segment. Accepts:
+ *
+ *   - bare Semantic Scholar paperId (40-char hex)
+ *   - DOI (with or without `doi:` / `https://doi.org/` prefix)
+ *   - arXiv id (`1706.03762` / `1706.03762v3` / `cs/0501067`)
+ *   - typed prefixes Semantic Scholar accepts verbatim (`ARXIV:`, `MAG:`,
+ *     `ACL:`, `PMID:`, `PMCID:`, `URL:`, `CorpusId:`, `DBLP:`)
+ *   - full `https://www.semanticscholar.org/paper/<paperId>` URL
+ */
+export function requirePaperRef(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) {
+        throw new ArgumentError(
+            'semanticscholar paper id cannot be empty',
+            'Example: opencli semanticscholar paper 10.18653/v1/N19-1423',
+        );
+    }
+    const s2Url = raw.match(/^https?:\/\/(?:www\.)?semanticscholar\.org\/paper\/(?:[^/]+\/)?([0-9a-f]{40})/i);
+    if (s2Url) return s2Url[1].toLowerCase();
+    if (S2_PAPER_ID.test(raw)) return raw.toLowerCase();
+    if (PREFIXED.test(raw)) return raw;
+    if (/^doi:/i.test(raw)) {
+        const doi = raw.replace(/^doi:/i, '').trim();
+        if (DOI_BARE.test(doi)) return `DOI:${doi}`;
+    }
+    const doiUrl = raw.match(/^https?:\/\/(?:dx\.)?doi\.org\/(.+)$/i);
+    if (doiUrl && DOI_BARE.test(doiUrl[1])) return `DOI:${doiUrl[1]}`;
+    if (DOI_BARE.test(raw)) return `DOI:${raw}`;
+    if (ARXIV_MODERN.test(raw) || ARXIV_LEGACY.test(raw)) return `ARXIV:${raw}`;
+    throw new ArgumentError(
+        `semanticscholar paper id "${value}" is not recognised`,
+        'Use a Semantic Scholar paperId, a DOI, an arXiv id, or a prefixed id (e.g. "ARXIV:1706.03762", "PMID:12345").',
+    );
+}
+
+/**
+ * Fetch with optional `SEMANTIC_SCHOLAR_API_KEY` header. Retries once on 429
+ * after a short pause; anonymous traffic hits the public ~100 req / 5 min
+ * cap, and a single retry covers the typical burst-then-cool-down case.
+ */
+export async function s2Fetch(url, label) {
+    const headers = { 'user-agent': UA, accept: 'application/json' };
+    const apiKey = process.env.SEMANTIC_SCHOLAR_API_KEY;
+    if (apiKey) headers['x-api-key'] = apiKey;
+
+    let resp;
+    let attempt = 0;
+    while (true) {
+        try {
+            resp = await fetch(url, { headers });
+        } catch (err) {
+            throw new CommandExecutionError(
+                `${label} request failed: ${err?.message ?? err}`,
+                'Check that api.semanticscholar.org is reachable from this network.',
+            );
+        }
+        if (resp.status === 429 && attempt === 0 && !apiKey) {
+            attempt += 1;
+            await new Promise(resolve => setTimeout(resolve, 1500));
+            continue;
+        }
+        break;
+    }
+
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Semantic Scholar returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Semantic Scholar throttles anonymous traffic; set SEMANTIC_SCHOLAR_API_KEY (free at https://www.semanticscholar.org/product/api) or wait a minute 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}`);
+    }
+    if (body && typeof body === 'object' && body.error) {
+        throw new CommandExecutionError(`${label} returned an error: ${body.error}`);
+    }
+    return body;
+}
+
+/** Return the AI-generated one-line summary if present, else ''. */
+export function tldrText(tldr) {
+    if (tldr && typeof tldr === 'object' && typeof tldr.text === 'string') {
+        return tldr.text.trim();
+    }
+    return '';
+}
+
+/** First author display name, or '' when authors is missing. */
+export function firstAuthorName(authors) {
+    if (!Array.isArray(authors) || !authors.length) return '';
+    const first = authors[0];
+    if (first && typeof first === 'object' && typeof first.name === 'string') {
+        return first.name.trim();
+    }
+    return '';
+}
+
+export function optionalNumber(value, label) {
+    if (value == null) return null;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new CommandExecutionError(`semanticscholar ${label} must be a number when present`);
+    }
+    return value;
+}
+
+export function normalizePaperRow(paper, label, { rank } = {}) {
+    if (!paper || typeof paper !== 'object') {
+        throw new CommandExecutionError(`semanticscholar ${label} row is not an object`);
+    }
+    if (typeof paper.paperId !== 'string' || !paper.paperId.trim()) {
+        throw new CommandExecutionError(`semanticscholar ${label} row is missing paperId`);
+    }
+    if (typeof paper.title !== 'string' || !paper.title.trim()) {
+        throw new CommandExecutionError(`semanticscholar ${label} row is missing title`);
+    }
+    if (paper.authors != null && !Array.isArray(paper.authors)) {
+        throw new CommandExecutionError(`semanticscholar ${label} row has malformed authors`);
+    }
+    const row = {
+        paperId: paper.paperId.trim(),
+        doi: pickDoi(paper.externalIds),
+        title: paper.title.trim(),
+        year: optionalNumber(paper.year, `${label} year`),
+        firstAuthor: firstAuthorName(paper.authors),
+        citationCount: optionalNumber(paper.citationCount, `${label} citationCount`),
+        url: typeof paper.url === 'string' && paper.url.trim()
+            ? paper.url.trim()
+            : `https://www.semanticscholar.org/paper/${paper.paperId.trim()}`,
+    };
+    if (rank != null) return { rank, ...row };
+    return row;
+}
+
+/** Strip the typed prefix from `externalIds.DOI` and similar. */
+export function pickDoi(externalIds) {
+    if (externalIds && typeof externalIds === 'object' && typeof externalIds.DOI === 'string') {
+        return externalIds.DOI;
+    }
+    return '';
+}

package/clis/sinablog/article.js

@@ -0,0 +1,15 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { loadSinaBlogArticle } from './utils.js';
+cli({
+    site: 'sinablog',
+    name: 'article',
+    access: 'read',
+    description: '获取新浪博客单篇文章详情',
+    domain: 'blog.sina.com.cn',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'url', required: true, positional: true, help: '文章URL（如 https://blog.sina.com.cn/s/blog_xxx.html）' },
+    ],
+    columns: ['title', 'author', 'date', 'category', 'readCount', 'commentCount'],
+    func: async (page, args) => loadSinaBlogArticle(page, args.url),
+});

package/clis/sinablog/hot.js

@@ -0,0 +1,15 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { loadSinaBlogHot } from './utils.js';
+cli({
+    site: 'sinablog',
+    name: 'hot',
+    access: 'read',
+    description: '获取新浪博客热门文章/推荐',
+    domain: 'blog.sina.com.cn',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: '返回的文章数量' },
+    ],
+    columns: ['rank', 'title', 'author', 'date', 'readCount', 'url'],
+    func: async (page, args) => loadSinaBlogHot(page, Number(args.limit) || 20),
+});

package/clis/sinablog/search.js

@@ -0,0 +1,52 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+function normalize(value) {
+    return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+}
+function stripHtml(value) {
+    return value.replace(/<[^>]+>/g, '');
+}
+async function searchSinaBlog(keyword, limit) {
+    const url = new URL('https://search.sina.com.cn/api/search');
+    url.searchParams.set('q', keyword);
+    url.searchParams.set('tp', 'mix');
+    url.searchParams.set('sort', '0');
+    url.searchParams.set('page', '1');
+    url.searchParams.set('size', String(Math.max(limit, 10)));
+    url.searchParams.set('from', 'search_result');
+    const resp = await fetch(url, {
+        headers: {
+            'User-Agent': 'Mozilla/5.0',
+            Accept: 'application/json',
+        },
+    });
+    if (!resp.ok)
+        throw new Error(`Sina blog search failed: HTTP ${resp.status}`);
+    const data = await resp.json();
+    const list = Array.isArray(data?.data?.list) ? data.data.list : [];
+    return list
+        .filter((item) => normalize(item?.url).includes('blog.sina.com.cn/s/blog_'))
+        .slice(0, limit)
+        .map((item, index) => ({
+        rank: index + 1,
+        title: normalize(stripHtml(item?.title || '')),
+        author: normalize(item?.media_show || item?.author),
+        date: normalize(item?.time || item?.dataTime),
+        description: normalize(item?.intro || item?.searchSummary).slice(0, 150),
+        url: normalize(item?.url),
+    }));
+}
+cli({
+    site: 'sinablog',
+    name: 'search',
+    access: 'read',
+    description: '搜索新浪博客文章（通过新浪搜索）',
+    domain: 'blog.sina.com.cn',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'keyword', required: true, positional: true, help: '搜索关键词' },
+        { name: 'limit', type: 'int', default: 20, help: '返回的文章数量' },
+    ],
+    columns: ['rank', 'title', 'author', 'date', 'description', 'url'],
+    func: async (args) => searchSinaBlog(args.keyword, Math.max(1, Math.min(Number(args.limit) || 20, 50))),
+});

package/clis/sinablog/user.js

@@ -0,0 +1,16 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { loadSinaBlogUser } from './utils.js';
+cli({
+    site: 'sinablog',
+    name: 'user',
+    access: 'read',
+    description: '获取新浪博客用户的文章列表',
+    domain: 'blog.sina.com.cn',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'uid', required: true, positional: true, help: '新浪博客用户ID（如 1234567890）' },
+        { name: 'limit', type: 'int', default: 20, help: '返回的文章数量' },
+    ],
+    columns: ['rank', 'title', 'author', 'date', 'readCount', 'url'],
+    func: async (page, args) => loadSinaBlogUser(page, args.uid, Number(args.limit) || 20),
+});