@jackwener/opencli 1.8.0 → 1.8.1

package/clis/weread/book-search.js

@@ -0,0 +1,438 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { WEREAD_UA, WEREAD_WEB_ORIGIN } from './utils.js';
+
+const MAX_LIMIT = 100;
+const MAX_FRAGMENT_SIZE = 500;
+const SEARCH_PAGE_SIZE = 50;
+
+function decodeHtmlText(value) {
+    return String(value || '')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&#x([0-9a-fA-F]+);/gi, (_, n) => String.fromCharCode(parseInt(n, 16)))
+        .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&quot;/g, '"')
+        .trim();
+}
+
+function normalizeSearchText(value) {
+    return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function normalizePositiveInteger(value, defaultValue, label, maxValue) {
+    const raw = value ?? defaultValue;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`${label} must be a positive integer`);
+    }
+    if (maxValue != null && n > maxValue) {
+        throw new ArgumentError(`${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+function parseOptionalFiniteNumber(value) {
+    if (value == null || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+
+function parseHasMore(value) {
+    if (value === true || value === 1 || value === '1')
+        return true;
+    if (value === false || value === 0 || value === '0')
+        return false;
+    return null;
+}
+
+function normalizeRequiredString(value, label) {
+    const text = normalizeSearchText(value);
+    if (!text) {
+        throw new ArgumentError(`${label} is required`);
+    }
+    return text;
+}
+
+function parseWereadReaderUrl(value) {
+    let url;
+    try {
+        url = new URL(String(value || ''), WEREAD_WEB_ORIGIN);
+    }
+    catch {
+        return '';
+    }
+    const pathParts = url.pathname.split('/').filter(Boolean);
+    if (url.protocol !== 'https:' || url.hostname !== 'weread.qq.com' || pathParts[0] !== 'web' || pathParts[1] !== 'reader' || !pathParts[2]) {
+        return '';
+    }
+    if (pathParts.length !== 3) {
+        return '';
+    }
+    return url.toString();
+}
+
+async function fetchJson(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url.toString(), {
+            headers: { 'User-Agent': WEREAD_UA },
+        });
+    }
+    catch (error) {
+        throw new CommandExecutionError(`${label} request failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} request failed: HTTP ${resp.status}`);
+    }
+    try {
+        return await resp.json();
+    }
+    catch {
+        throw new CommandExecutionError(`${label} returned invalid JSON`);
+    }
+}
+
+async function fetchText(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url.toString(), {
+            headers: { 'User-Agent': WEREAD_UA },
+        });
+    }
+    catch (error) {
+        throw new CommandExecutionError(`${label} request failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} request failed: HTTP ${resp.status}`);
+    }
+    return resp.text();
+}
+
+function buildReaderUrlFromInfoId(infoId) {
+    const text = normalizeSearchText(infoId);
+    return text ? `${WEREAD_WEB_ORIGIN}/web/reader/${text}` : '';
+}
+
+function extractReaderInitialState(html) {
+    const marker = 'window.__INITIAL_STATE__=';
+    const start = html.indexOf(marker);
+    if (start < 0)
+        return null;
+    const jsonStart = start + marker.length;
+    const cleanupStart = html.indexOf(';(function(){var s;', jsonStart);
+    const scriptEnd = html.indexOf('</script>', jsonStart);
+    const jsonEnd = cleanupStart >= 0 ? cleanupStart : scriptEnd;
+    if (jsonEnd < 0)
+        return null;
+    try {
+        return JSON.parse(html.slice(jsonStart, jsonEnd));
+    }
+    catch {
+        return null;
+    }
+}
+
+function extractJsonLdBookInfo(html) {
+    const match = html.match(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/i);
+    if (!match)
+        return {};
+    try {
+        const data = JSON.parse(match[1]);
+        const info = {};
+        info.bookId = normalizeSearchText(data?.['@Id']);
+        info.title = normalizeSearchText(data?.name);
+        info.author = normalizeSearchText(data?.author?.name);
+        info.readerUrl = normalizeSearchText(data?.url);
+        return info;
+    }
+    catch {
+        return {};
+    }
+}
+
+function parseReaderMetadata(html, readerUrl) {
+    const state = extractReaderInitialState(html);
+    const reader = state?.reader ?? {};
+    const info = reader.bookInfo ?? {};
+    const jsonLd = extractJsonLdBookInfo(html);
+    const chapters = Array.isArray(reader.chapterInfos) ? reader.chapterInfos : [];
+    const infoId = normalizeSearchText(reader.infoId) || normalizeSearchText(info.encodeId);
+    const metadata = {};
+    metadata.bookId = normalizeSearchText(info.bookId) || normalizeSearchText(reader.bookId) || jsonLd.bookId;
+    metadata.title = normalizeSearchText(info.title) || jsonLd.title;
+    metadata.author = normalizeSearchText(info.author) || jsonLd.author;
+    metadata.readerUrl = normalizeSearchText(readerUrl) || buildReaderUrlFromInfoId(infoId) || jsonLd.readerUrl;
+    metadata.chapters = chapters;
+    return metadata;
+}
+
+async function loadReaderMetadata(readerUrl) {
+    if (!readerUrl)
+        return null;
+    const html = await fetchText(readerUrl, 'WeRead reader page');
+    const metadata = parseReaderMetadata(html, readerUrl);
+    return metadata.bookId ? metadata : null;
+}
+
+function parseSearchHtmlEntries(html) {
+    const items = Array.from(html.matchAll(/<li[^>]*class="wr_bookList_item"[^>]*>([\s\S]*?)<\/li>/g));
+    return items.map((match) => {
+        const chunk = match[1];
+        const hrefMatch = chunk.match(/<a[^>]*href="([^"]+)"[^>]*class="wr_bookList_item_link"[^>]*>|<a[^>]*class="wr_bookList_item_link"[^>]*href="([^"]+)"[^>]*>/);
+        const titleMatch = chunk.match(/<p[^>]*class="wr_bookList_item_title"[^>]*>([\s\S]*?)<\/p>/);
+        const authorMatch = chunk.match(/<p[^>]*class="wr_bookList_item_author"[^>]*>([\s\S]*?)<\/p>/);
+        const href = hrefMatch?.[1] || hrefMatch?.[2] || '';
+        const entry = {};
+        entry.title = decodeHtmlText(titleMatch?.[1] || '');
+        entry.author = decodeHtmlText(authorMatch?.[1] || '');
+        entry.readerUrl = href ? parseWereadReaderUrl(href) : '';
+        return entry;
+    }).filter((entry) => entry.title && entry.readerUrl);
+}
+
+async function loadSearchHtmlEntries(bookQuery) {
+    const url = new URL('/web/search/books', WEREAD_WEB_ORIGIN);
+    url.searchParams.set('keyword', bookQuery);
+    return parseSearchHtmlEntries(await fetchText(url, 'WeRead search page'));
+}
+
+function resolveReaderUrlForBook(book, htmlEntries) {
+    const title = normalizeSearchText(book.title);
+    const author = normalizeSearchText(book.author);
+    if (!title)
+        return '';
+    if (author) {
+        const exact = htmlEntries.filter((entry) => normalizeSearchText(entry.title) === title && normalizeSearchText(entry.author) === author);
+        if (exact.length === 1)
+            return exact[0].readerUrl;
+    }
+    const sameTitle = htmlEntries.filter((entry) => normalizeSearchText(entry.title) === title);
+    return sameTitle.length === 1 ? sameTitle[0].readerUrl : '';
+}
+
+async function searchBookByQuery(bookQuery, bookRank) {
+    const url = new URL('/web/search/global', `${WEREAD_WEB_ORIGIN}/web`);
+    url.searchParams.set('keyword', bookQuery);
+    const data = await fetchJson(url, 'WeRead book search');
+    if (!Array.isArray(data?.books)) {
+        throw new CommandExecutionError('WeRead book search returned malformed books');
+    }
+    const books = data.books;
+    if (books.length === 0) {
+        throw new EmptyResultError('weread book-search', `No WeRead books found for "${bookQuery}"`);
+    }
+    if (bookRank > books.length) {
+        throw new ArgumentError(`book-rank must be <= ${books.length}`, `Only ${books.length} book search result(s) were returned for "${bookQuery}"`);
+    }
+    const bookInfo = books[bookRank - 1]?.bookInfo ?? {};
+    const selected = {
+        bookId: normalizeSearchText(bookInfo.bookId),
+        title: normalizeSearchText(bookInfo.title),
+        author: normalizeSearchText(bookInfo.author),
+        readerUrl: '',
+        chapters: [],
+    };
+    if (!selected.bookId) {
+        throw new CommandExecutionError(`WeRead book search result ${bookRank} is missing bookId`);
+    }
+    const htmlEntries = await loadSearchHtmlEntries(bookQuery);
+    selected.readerUrl = resolveReaderUrlForBook(selected, htmlEntries);
+    const readerMetadata = await loadReaderMetadata(selected.readerUrl);
+    return {
+        ...selected,
+        ...Object.fromEntries(Object.entries(readerMetadata ?? {}).filter(([, value]) => value != null && value !== '' && !(Array.isArray(value) && value.length === 0))),
+    };
+}
+
+async function resolveBookTarget(target, bookRank) {
+    if (/^https?:\/\//i.test(target)) {
+        const readerUrl = parseWereadReaderUrl(target);
+        if (!readerUrl) {
+            throw new ArgumentError('book URL must be a https://weread.qq.com/web/reader/<id> URL');
+        }
+        const metadata = await loadReaderMetadata(readerUrl);
+        if (!metadata?.bookId) {
+            throw new CommandExecutionError('Could not parse a bookId from the reader URL');
+        }
+        return metadata;
+    }
+    if (/^\d+$/.test(target)) {
+        const metadata = {};
+        metadata.bookId = target;
+        metadata.title = '';
+        metadata.author = '';
+        metadata.readerUrl = '';
+        metadata.chapters = [];
+        return metadata;
+    }
+    return searchBookByQuery(target, bookRank);
+}
+
+async function searchWithinBook(bookId, query, limit, fragmentSize) {
+    const rows = [];
+    let maxIdx = 0;
+    while (rows.length < limit) {
+        const remaining = limit - rows.length;
+        const pageSize = remaining < SEARCH_PAGE_SIZE ? remaining : SEARCH_PAGE_SIZE;
+        const url = new URL('/web/book/search', WEREAD_WEB_ORIGIN);
+        url.searchParams.set('bookId', bookId);
+        url.searchParams.set('keyword', query);
+        url.searchParams.set('maxIdx', String(maxIdx));
+        url.searchParams.set('count', String(pageSize));
+        url.searchParams.set('fragmentSize', String(fragmentSize));
+        url.searchParams.set('onlyCount', '0');
+        const data = await fetchJson(url, 'WeRead in-book search');
+        if (!Array.isArray(data?.result)) {
+            throw new CommandExecutionError('WeRead in-book search returned malformed result');
+        }
+        const result = data.result.map((item) => {
+            if (!item || typeof item !== 'object') {
+                throw new CommandExecutionError('WeRead in-book search returned malformed match');
+            }
+            const snippet = normalizeSearchText(item.abstract);
+            const searchIdx = parseOptionalFiniteNumber(item.searchIdx);
+            if (!snippet || searchIdx == null || searchIdx <= 0) {
+                throw new CommandExecutionError('WeRead in-book search returned malformed match');
+            }
+            return {
+                ...item,
+                abstract: snippet,
+                chapterIdx: parseOptionalFiniteNumber(item.chapterIdx),
+                chapterUid: parseOptionalFiniteNumber(item.chapterUid),
+                searchIdx,
+            };
+        });
+        if (result.length === 0)
+            break;
+        rows.push(...result);
+        const lastSearchIdx = result[result.length - 1].searchIdx;
+        if (lastSearchIdx <= maxIdx)
+            throw new CommandExecutionError('WeRead in-book search returned non-advancing searchIdx');
+        maxIdx = lastSearchIdx;
+        if (rows.length >= limit)
+            break;
+        const hasMore = parseHasMore(data?.hasMore);
+        if (hasMore == null) {
+            if (result.length < pageSize)
+                break;
+            throw new CommandExecutionError('WeRead in-book search returned malformed pagination state');
+        }
+        if (!hasMore)
+            break;
+    }
+    if (rows.length === 0) {
+        throw new EmptyResultError('weread book-search', `No matches for "${query}" in book ${bookId}`);
+    }
+    return rows.slice(0, limit);
+}
+
+function buildChapterMap(chapters) {
+    const map = new Map();
+    for (const chapter of chapters) {
+        const chapterUid = parseOptionalFiniteNumber(chapter?.chapterUid);
+        if (chapterUid == null)
+            continue;
+        map.set(chapterUid, {
+            chapterIdx: parseOptionalFiniteNumber(chapter?.chapterIdx),
+            chapterTitle: normalizeSearchText(chapter?.title),
+        });
+    }
+    return map;
+}
+
+function buildRows(book, matches) {
+    const chapterMap = buildChapterMap(book.chapters ?? []);
+    return matches.map((item, index) => {
+        const chapterUid = parseOptionalFiniteNumber(item?.chapterUid);
+        const chapter = chapterMap.get(chapterUid) ?? {};
+        const chapterIdx = chapter.chapterIdx ?? parseOptionalFiniteNumber(item?.chapterIdx);
+        return {
+            rank: index + 1,
+            book_title: book.title || null,
+            author: book.author || null,
+            chapter_idx: chapterIdx,
+            chapter_title: chapter.chapterTitle || null,
+            snippet: normalizeSearchText(item?.abstract),
+            search_idx: item.searchIdx,
+            chapter_uid: chapterUid,
+            book_id: book.bookId,
+            url: book.readerUrl || null,
+        };
+    });
+}
+
+function formatMarkdownResults(book, query, rows) {
+    const title = book.title || `WeRead book ${book.bookId}`;
+    const lines = [`# ${title}`];
+    if (book.author)
+        lines.push(`- author: ${book.author}`);
+    lines.push(`- book_id: \`${book.bookId}\``);
+    lines.push(`- query: \`${query}\``);
+    lines.push(`- matches: ${rows.length}`);
+    if (book.readerUrl)
+        lines.push(`- url: ${book.readerUrl}`);
+    lines.push('');
+    for (const row of rows) {
+        const chapterLabel = row.chapter_title || `chapter ${row.chapter_uid ?? ''}`.trim();
+        lines.push(`## ${row.rank}. ${chapterLabel}`);
+        const details = [];
+        if (row.chapter_idx !== null)
+            details.push(`chapter_idx: ${row.chapter_idx}`);
+        if (row.chapter_uid !== null)
+            details.push(`chapter_uid: ${row.chapter_uid}`);
+        details.push(`search_idx: ${row.search_idx}`);
+        lines.push('');
+        lines.push(`> ${row.snippet}`);
+        lines.push('');
+        for (const detail of details) {
+            lines.push(`- ${detail}`);
+        }
+        if (row.rank < rows.length)
+            lines.push('');
+    }
+    return lines.join('\n');
+}
+
+cli({
+    site: 'weread',
+    name: 'book-search',
+    access: 'read',
+    description: 'Search within a WeRead book after resolving it by title',
+    domain: 'weread.qq.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    defaultFormat: 'md',
+    args: [
+        { name: 'book', positional: true, required: true, help: 'Book title keyword, numeric bookId, or reader URL' },
+        { name: 'query', positional: true, required: true, help: 'Keyword to search inside the selected book' },
+        { name: 'book-rank', type: 'int', default: 1, help: 'Which book search result to use when book is a title keyword' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max in-book matches to return (1-100)' },
+        { name: 'fragment-size', type: 'int', default: 150, help: 'Snippet length around each match (1-500)' },
+        { name: 'raw', type: 'boolean', default: false, help: 'Output structured rows instead of markdown text' },
+    ],
+    func: async (args) => {
+        const bookTarget = normalizeRequiredString(args.book, 'book');
+        const query = normalizeRequiredString(args.query, 'query');
+        const bookRank = normalizePositiveInteger(args['book-rank'], 1, 'book-rank');
+        const limit = normalizePositiveInteger(args.limit, 20, 'limit', MAX_LIMIT);
+        const fragmentSize = normalizePositiveInteger(args['fragment-size'], 150, 'fragment-size', MAX_FRAGMENT_SIZE);
+        const book = await resolveBookTarget(bookTarget, bookRank);
+        const matches = await searchWithinBook(book.bookId, query, limit, fragmentSize);
+        const rows = buildRows(book, matches);
+        if (Boolean(args.raw))
+            return rows;
+        return [{ markdown: formatMarkdownResults(book, query, rows) }];
+    },
+});
+
+export const __test__ = {
+    buildRows,
+    extractReaderInitialState,
+    formatMarkdownResults,
+    parseReaderMetadata,
+    parseSearchHtmlEntries,
+    resolveReaderUrlForBook,
+};

package/clis/weread/book-search.test.js

@@ -0,0 +1,242 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './book-search.js';
+
+function jsonResponse(body, status = 200) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: () => Promise.resolve(body),
+    };
+}
+
+function textResponse(body, status = 200) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        text: () => Promise.resolve(body),
+    };
+}
+
+function readerHtml({ bookId = 'book-1', title = '史记', author = '司马迁', chapters = [] } = {}) {
+    const state = {
+        reader: {
+            infoId: 'reader-1',
+            bookId,
+            bookInfo: { bookId, title, author, encodeId: 'reader-1' },
+            chapterInfos: chapters,
+        },
+    };
+    return `
+      <html>
+        <head>
+          <script type="application/ld+json">{"@Id":"${bookId}","name":"${title}","author":{"name":"${author}"},"url":"https://weread.qq.com/web/reader/reader-1"}</script>
+        </head>
+        <body>
+          <script>window.__INITIAL_STATE__=${JSON.stringify(state)};(function(){var s;(s=document.currentScript).parentNode.removeChild(s);}());</script>
+        </body>
+      </html>
+    `;
+}
+
+describe('weread/book-search', () => {
+    const command = getRegistry().get('weread/book-search');
+
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        vi.unstubAllGlobals();
+    });
+
+    it('registers book-search with markdown default output', () => {
+        expect(command?.defaultFormat).toBe('md');
+    });
+
+    it('resolves a book by title, reads reader chapter metadata, and searches inside the book', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce(jsonResponse({
+            books: [
+                {
+                    bookInfo: {
+                        title: '史记',
+                        author: '司马迁',
+                        bookId: 'book-1',
+                    },
+                },
+            ],
+        }))
+            .mockResolvedValueOnce(textResponse(`
+          <ul class="search_bookDetail_list">
+            <li class="wr_bookList_item">
+              <a class="wr_bookList_item_link" href="/web/reader/reader-1"></a>
+              <p class="wr_bookList_item_title">史记</p>
+              <p class="wr_bookList_item_author">司马迁</p>
+            </li>
+          </ul>
+        `))
+            .mockResolvedValueOnce(textResponse(readerHtml({
+            bookId: 'book-1',
+            title: '史记',
+            author: '司马迁',
+            chapters: [
+                { chapterUid: 171, chapterIdx: 9, title: '卷一 五帝本纪第一' },
+            ],
+        })))
+            .mockResolvedValueOnce(jsonResponse({
+            result: [
+                {
+                    chapterUid: 171,
+                    abstract: '尧、舜二帝举贤任能，天下大治。',
+                    absStart: 100,
+                    absEnd: 118,
+                    keyword: ['舜'],
+                    searchIdx: 1,
+                },
+            ],
+            hasMore: 0,
+        }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const result = await command.func({ book: '史记', query: '舜', limit: 5, 'book-rank': 1 });
+
+        expect(String(fetchMock.mock.calls[0][0])).toContain('/web/search/global?keyword=');
+        expect(String(fetchMock.mock.calls[1][0])).toContain('/web/search/books?keyword=');
+        expect(fetchMock.mock.calls[2][0]).toBe('https://weread.qq.com/web/reader/reader-1');
+        expect(String(fetchMock.mock.calls[3][0])).toContain('/web/book/search?bookId=book-1');
+        expect(String(fetchMock.mock.calls[3][0])).toContain('keyword=%E8%88%9C');
+        expect(result).toEqual([
+            {
+                markdown: [
+                    '# 史记',
+                    '- author: 司马迁',
+                    '- book_id: `book-1`',
+                    '- query: `舜`',
+                    '- matches: 1',
+                    '- url: https://weread.qq.com/web/reader/reader-1',
+                    '',
+                    '## 1. 卷一 五帝本纪第一',
+                    '',
+                    '> 尧、舜二帝举贤任能，天下大治。',
+                    '',
+                    '- chapter_idx: 9',
+                    '- chapter_uid: 171',
+                    '- search_idx: 1',
+                ].join('\n'),
+            },
+        ]);
+    });
+
+    it('uses book-rank to choose among search results and paginates by searchIdx', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce(jsonResponse({
+            books: [
+                { bookInfo: { title: '文明', author: '作者甲', bookId: 'wrong-book' } },
+                { bookInfo: { title: '文明', author: '作者乙', bookId: 'right-book' } },
+            ],
+        }))
+            .mockResolvedValueOnce(textResponse('<html></html>'))
+            .mockResolvedValueOnce(jsonResponse({
+            result: [
+                { chapterUid: 1, abstract: 'first', searchIdx: 1 },
+                { chapterUid: 1, abstract: 'second', searchIdx: 2 },
+            ],
+            hasMore: 1,
+        }))
+            .mockResolvedValueOnce(jsonResponse({
+            result: [
+                { chapterUid: 2, abstract: 'third', searchIdx: 3 },
+            ],
+            hasMore: 0,
+        }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const result = await command.func({ book: '文明', query: '德', 'book-rank': 2, limit: 3, raw: true });
+
+        expect(String(fetchMock.mock.calls[2][0])).toContain('bookId=right-book');
+        expect(String(fetchMock.mock.calls[2][0])).toContain('maxIdx=0');
+        expect(String(fetchMock.mock.calls[3][0])).toContain('maxIdx=2');
+        expect(result.map((row) => row.snippet)).toEqual(['first', 'second', 'third']);
+        expect(result.every((row) => row.book_id === 'right-book')).toBe(true);
+    });
+
+    it('throws EMPTY_RESULT when no book matches the title query', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ books: [] })));
+
+        await expect(command.func({ book: 'not-a-book', query: 'x' })).rejects.toMatchObject({
+            code: 'EMPTY_RESULT',
+        });
+    });
+
+    it('fails closed when the book search payload is malformed', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ result: [] })));
+
+        await expect(command.func({ book: '史记', query: '舜' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: 'WeRead book search returned malformed books',
+        });
+    });
+
+    it('rejects off-domain reader URLs instead of fetching arbitrary pages', async () => {
+        expect(command?.func).toBeTypeOf('function');
+
+        await expect(command.func({ book: 'https://example.com/web/reader/reader-1', query: '舜' })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: 'book URL must be a https://weread.qq.com/web/reader/<id> URL',
+        });
+    });
+
+    it('fails closed when in-book search results are malformed', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ result: [{ searchIdx: 1 }], hasMore: 0 })));
+
+        await expect(command.func({ book: '123', query: '舜', raw: true })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: 'WeRead in-book search returned malformed match',
+        });
+    });
+
+    it('fails closed when in-book pagination does not advance', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        vi.stubGlobal('fetch', vi.fn()
+            .mockResolvedValueOnce(jsonResponse({
+            result: [{ chapterUid: 1, abstract: 'first', searchIdx: 1 }],
+            hasMore: 1,
+        }))
+            .mockResolvedValueOnce(jsonResponse({
+            result: [{ chapterUid: 1, abstract: 'second', searchIdx: 1 }],
+            hasMore: 1,
+        })));
+
+        await expect(command.func({ book: '123', query: '舜', limit: 2, raw: true })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: 'WeRead in-book search returned non-advancing searchIdx',
+        });
+    });
+
+    it('fails closed when a full in-book search page has no pagination state', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce(jsonResponse({
+            result: Array.from({ length: 50 }, (_, index) => ({
+                chapterUid: 1,
+                abstract: `match ${index + 1}`,
+                searchIdx: index + 1,
+            })),
+        })));
+
+        await expect(command.func({ book: '123', query: '舜', limit: 51, raw: true })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: 'WeRead in-book search returned malformed pagination state',
+        });
+    });
+
+    it('validates numeric arguments instead of silently clamping', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        await expect(command.func({ book: '史记', query: '舜', limit: 101 })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: 'limit must be <= 100',
+        });
+    });
+});