@jackwener/opencli 1.5.6 → 1.5.7

package/dist/clis/weread/book.js

@@ -1,6 +1,107 @@
 import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
-import { fetchPrivateApi, resolveShelfReaderUrl } from './utils.js';
+import { fetchPrivateApi, fetchWebApi, resolveShelfReader, WEREAD_UA, WEREAD_WEB_ORIGIN, } from './utils.js';
+function decodeHtmlText(value) {
+    return 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 value.replace(/\s+/g, ' ').trim();
+}
+function buildSearchIdentity(title, author) {
+    return `${normalizeSearchText(title)}\u0000${normalizeSearchText(author)}`;
+}
+function countSearchTitles(entries) {
+    const counts = new Map();
+    for (const entry of entries) {
+        const key = normalizeSearchText(entry.title);
+        if (!key)
+            continue;
+        counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    return counts;
+}
+function countSearchIdentities(entries) {
+    const counts = new Map();
+    for (const entry of entries) {
+        const key = buildSearchIdentity(entry.title, entry.author);
+        if (!normalizeSearchText(entry.title) || !normalizeSearchText(entry.author))
+            continue;
+        counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    return counts;
+}
+/**
+ * Reuse the public search page as a last-resort reader URL source when the
+ * cached shelf page cannot provide a trustworthy bookId-to-reader mapping.
+ */
+async function resolveSearchReaderUrl(title, author) {
+    const normalizedTitle = normalizeSearchText(title);
+    const normalizedAuthor = normalizeSearchText(author);
+    if (!normalizedTitle)
+        return '';
+    try {
+        const [data, htmlEntries] = await Promise.all([
+            fetchWebApi('/search/global', { keyword: normalizedTitle }),
+            (async () => {
+                const url = new URL('/web/search/books', WEREAD_WEB_ORIGIN);
+                url.searchParams.set('keyword', normalizedTitle);
+                const resp = await fetch(url.toString(), {
+                    headers: { 'User-Agent': WEREAD_UA },
+                });
+                if (!resp.ok)
+                    return [];
+                const html = await resp.text();
+                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] || '';
+                    return {
+                        title: decodeHtmlText(titleMatch?.[1] || ''),
+                        author: decodeHtmlText(authorMatch?.[1] || ''),
+                        url: href ? new URL(href, WEREAD_WEB_ORIGIN).toString() : '',
+                    };
+                }).filter((entry) => entry.title && entry.url);
+            })(),
+        ]);
+        const books = Array.isArray(data?.books) ? data.books : [];
+        const apiIdentityCounts = countSearchIdentities(books.map((item) => ({
+            title: item.bookInfo?.title ?? '',
+            author: item.bookInfo?.author ?? '',
+        })));
+        const htmlIdentityCounts = countSearchIdentities(htmlEntries.filter((entry) => entry.author));
+        const identityKey = buildSearchIdentity(normalizedTitle, normalizedAuthor);
+        if (normalizedAuthor &&
+            (apiIdentityCounts.get(identityKey) || 0) === 1 &&
+            (htmlIdentityCounts.get(identityKey) || 0) === 1) {
+            const exactMatch = htmlEntries.find((entry) => buildSearchIdentity(entry.title, entry.author) === identityKey);
+            if (exactMatch?.url)
+                return exactMatch.url;
+        }
+        const sameTitleHtmlEntries = htmlEntries.filter((entry) => normalizeSearchText(entry.title) === normalizedTitle);
+        if (normalizedAuthor && sameTitleHtmlEntries.some((entry) => normalizeSearchText(entry.author))) {
+            return '';
+        }
+        const apiTitleCounts = countSearchTitles(books.map((item) => ({ title: item.bookInfo?.title ?? '' })));
+        const htmlTitleCounts = countSearchTitles(htmlEntries);
+        if ((apiTitleCounts.get(normalizedTitle) || 0) !== 1 || (htmlTitleCounts.get(normalizedTitle) || 0) !== 1) {
+            return '';
+        }
+        return htmlEntries.find((entry) => normalizeSearchText(entry.title) === normalizedTitle)?.url || '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Read visible book metadata from the web reader cover/flyleaf page.
  * This path is used as a fallback when the private API session has expired.
@@ -92,7 +193,12 @@ cli({
             if (!(error instanceof CliError) || error.code !== 'AUTH_REQUIRED') {
                 throw error;
             }
-            const readerUrl = await resolveShelfReaderUrl(page, bookId);
+            const { readerUrl: resolvedReaderUrl, snapshot } = await resolveShelfReader(page, bookId);
+            let readerUrl = resolvedReaderUrl;
+            if (!readerUrl) {
+                const cachedBook = snapshot.rawBooks.find((book) => String(book?.bookId || '').trim() === bookId);
+                readerUrl = await resolveSearchReaderUrl(String(cachedBook?.title || ''), String(cachedBook?.author || ''));
+            }
             if (!readerUrl) {
                 throw error;
             }

package/dist/clis/weread/commands.test.js

@@ -18,8 +18,18 @@ describe('weread book-id positional args', () => {
     const book = getRegistry().get('weread/book');
     const highlights = getRegistry().get('weread/highlights');
     const notes = getRegistry().get('weread/notes');
+    const repeatValue = (value, count) => Array.from({ length: count }, () => value);
+    const createPageStub = (...evaluateResults) => ({
+        getCookies: vi.fn().mockResolvedValue([
+            { name: 'wr_vid', value: '70486028', domain: '.weread.qq.com' },
+        ]),
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockImplementation(async () => evaluateResults.shift()),
+    });
     beforeEach(() => {
         mockFetchPrivateApi.mockReset();
+        vi.unstubAllGlobals();
     });
     it('passes the positional book-id to book details', async () => {
         mockFetchPrivateApi.mockResolvedValue({ title: 'Three Body', newRating: 880 });
@@ -28,33 +38,23 @@ describe('weread book-id positional args', () => {
     });
     it('falls back to the shelf reader page when private API auth has expired', async () => {
         mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn()
-                .mockResolvedValueOnce({
-                cacheFound: true,
-                rawBooks: [
-                    { bookId: 'MP_WXS_3634777637', title: '文明、现代化、价值投资与中国', author: '李录' },
-                ],
-                shelfIndexes: [
-                    { bookId: 'MP_WXS_3634777637', idx: 0, role: 'book' },
-                ],
-            })
-                .mockResolvedValueOnce(['https://weread.qq.com/web/reader/6f5323f071bd7f7b6f521e8'])
-                .mockResolvedValueOnce({
-                title: '文明、现代化、价值投资与中国',
-                author: '李录',
-                publisher: '中信出版集团',
-                intro: '对中国未来几十年的预测。',
-                category: '',
-                rating: '84.1%',
-                metadataReady: true,
-            }),
-            getCookies: vi.fn().mockResolvedValue([
-                { name: 'wr_vid', value: '70486028', domain: '.weread.qq.com' },
-            ]),
-            wait: vi.fn().mockResolvedValue(undefined),
-        };
+        const page = createPageStub({
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'MP_WXS_3634777637', title: '文明、现代化、价值投资与中国', author: '李录' },
+            ],
+            shelfIndexes: [
+                { bookId: 'MP_WXS_3634777637', idx: 0, role: 'book' },
+            ],
+        }, ['https://weread.qq.com/web/reader/6f5323f071bd7f7b6f521e8'], {
+            title: '文明、现代化、价值投资与中国',
+            author: '李录',
+            publisher: '中信出版集团',
+            intro: '对中国未来几十年的预测。',
+            category: '',
+            rating: '84.1%',
+            metadataReady: true,
+        });
         const result = await book.func(page, { 'book-id': 'MP_WXS_3634777637' });
         expect(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
         expect(page.goto).toHaveBeenNthCalledWith(2, 'https://weread.qq.com/web/reader/6f5323f071bd7f7b6f521e8');
@@ -72,41 +72,31 @@ describe('weread book-id positional args', () => {
     });
     it('keeps mixed shelf entries aligned when resolving MP_WXS reader urls', async () => {
         mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn()
-                .mockResolvedValueOnce({
-                cacheFound: true,
-                rawBooks: [
-                    { bookId: 'MP_WXS_1', title: '公众号文章一', author: '作者甲' },
-                    { bookId: 'BOOK_2', title: '普通书二', author: '作者乙' },
-                    { bookId: 'MP_WXS_3', title: '公众号文章三', author: '作者丙' },
-                ],
-                shelfIndexes: [
-                    { bookId: 'MP_WXS_1', idx: 0, role: 'mp' },
-                    { bookId: 'BOOK_2', idx: 1, role: 'book' },
-                    { bookId: 'MP_WXS_3', idx: 2, role: 'mp' },
-                ],
-            })
-                .mockResolvedValueOnce([
-                'https://weread.qq.com/web/reader/mp1',
-                'https://weread.qq.com/web/reader/book2',
-                'https://weread.qq.com/web/reader/mp3',
-            ])
-                .mockResolvedValueOnce({
-                title: '公众号文章一',
-                author: '作者甲',
-                publisher: '微信读书',
-                intro: '第一篇文章。',
-                category: '',
-                rating: '',
-                metadataReady: true,
-            }),
-            getCookies: vi.fn().mockResolvedValue([
-                { name: 'wr_vid', value: '70486028', domain: '.weread.qq.com' },
-            ]),
-            wait: vi.fn().mockResolvedValue(undefined),
-        };
+        const page = createPageStub({
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'MP_WXS_1', title: '公众号文章一', author: '作者甲' },
+                { bookId: 'BOOK_2', title: '普通书二', author: '作者乙' },
+                { bookId: 'MP_WXS_3', title: '公众号文章三', author: '作者丙' },
+            ],
+            shelfIndexes: [
+                { bookId: 'MP_WXS_1', idx: 0, role: 'mp' },
+                { bookId: 'BOOK_2', idx: 1, role: 'book' },
+                { bookId: 'MP_WXS_3', idx: 2, role: 'mp' },
+            ],
+        }, [
+            'https://weread.qq.com/web/reader/mp1',
+            'https://weread.qq.com/web/reader/book2',
+            'https://weread.qq.com/web/reader/mp3',
+        ], {
+            title: '公众号文章一',
+            author: '作者甲',
+            publisher: '微信读书',
+            intro: '第一篇文章。',
+            category: '',
+            rating: '',
+            metadataReady: true,
+        });
         const result = await book.func(page, { 'book-id': 'MP_WXS_1' });
         expect(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
         expect(page.goto).toHaveBeenNthCalledWith(2, 'https://weread.qq.com/web/reader/mp1');
@@ -123,79 +113,209 @@ describe('weread book-id positional args', () => {
     });
     it('rethrows AUTH_REQUIRED when shelf ordering is incomplete and reader urls cannot be trusted', async () => {
         mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn()
-                .mockResolvedValueOnce({
-                cacheFound: true,
-                rawBooks: [
-                    { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
-                    { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
-                ],
-                shelfIndexes: [
-                    { bookId: 'BOOK_2', idx: 0, role: 'book' },
-                ],
-            })
-                .mockResolvedValueOnce([
-                'https://weread.qq.com/web/reader/book2',
-                'https://weread.qq.com/web/reader/book1',
-            ]),
-            getCookies: vi.fn().mockResolvedValue([
-                { name: 'wr_vid', value: '70486028', domain: '.weread.qq.com' },
-            ]),
-            wait: vi.fn().mockResolvedValue(undefined),
-        };
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network disabled')));
+        const page = createPageStub({
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
+                { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
+            ],
+            shelfIndexes: [
+                { bookId: 'BOOK_2', idx: 0, role: 'book' },
+            ],
+        }, [
+            'https://weread.qq.com/web/reader/book2',
+            'https://weread.qq.com/web/reader/book1',
+        ]);
         await expect(book.func(page, { 'book-id': 'BOOK_1' })).rejects.toMatchObject({
             code: 'AUTH_REQUIRED',
             message: 'Not logged in to WeRead',
         });
         expect(page.goto).toHaveBeenCalledTimes(1);
-        expect(page.goto).toHaveBeenCalledWith('https://weread.qq.com/web/shelf');
+        expect(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
     });
-    it('waits for shelf indexes to hydrate before resolving a trusted reader url', async () => {
+    it('falls back to the public search page when a cached ordinary book has no trusted shelf reader url', async () => {
         mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn()
-                .mockResolvedValueOnce({
-                cacheFound: true,
-                rawBooks: [
-                    { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
-                    { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
-                ],
-                shelfIndexes: [
-                    { bookId: 'BOOK_2', idx: 0, role: 'book' },
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve({
+                books: [
+                    {
+                        bookInfo: {
+                            title: '数据化运营：系统方法与实践案例',
+                            author: '赵宏田 江丽萍 李宁',
+                            bookId: '22920382',
+                        },
+                    },
                 ],
-            })
-                .mockResolvedValueOnce({
-                cacheFound: true,
-                rawBooks: [
-                    { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
-                    { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
-                ],
-                shelfIndexes: [
-                    { bookId: 'BOOK_2', idx: 0, role: 'book' },
-                    { bookId: 'BOOK_1', idx: 1, role: 'book' },
-                ],
-            })
-                .mockResolvedValueOnce([
-                'https://weread.qq.com/web/reader/book2',
-                'https://weread.qq.com/web/reader/book1',
-            ])
-                .mockResolvedValueOnce({
-                title: '第一本',
-                author: '作者甲',
-                publisher: '出版社甲',
-                intro: '简介甲',
+            }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            text: () => Promise.resolve(`
+          <ul class="search_bookDetail_list">
+            <li class="wr_bookList_item">
+              <a class="wr_bookList_item_link" href="/web/reader/book229"></a>
+              <p class="wr_bookList_item_title">数据化运营：系统方法与实践案例</p>
+              <p class="wr_bookList_item_author">赵宏田 江丽萍 李宁</p>
+            </li>
+          </ul>
+        `),
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const staleSnapshot = {
+            cacheFound: true,
+            rawBooks: [
+                { bookId: '22920382', title: '数据化运营：系统方法与实践案例', author: '赵宏田 江丽萍 李宁' },
+            ],
+            shelfIndexes: [
+                { bookId: 'stale-entry', idx: 0, role: 'book' },
+            ],
+        };
+        const page = createPageStub(...repeatValue(staleSnapshot, 2), {
+            title: '数据化运营：系统方法与实践案例',
+            author: '赵宏田 江丽萍 李宁',
+            publisher: '电子工业出版社',
+            intro: '一本关于数据化运营的方法论书籍。',
+            category: '',
+            rating: '',
+            metadataReady: true,
+        });
+        const result = await book.func(page, { 'book-id': '22920382' });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        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(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
+        expect(page.goto).toHaveBeenNthCalledWith(2, 'https://weread.qq.com/web/reader/book229');
+        expect(result).toEqual([
+            {
+                title: '数据化运营：系统方法与实践案例',
+                author: '赵宏田 江丽萍 李宁',
+                publisher: '电子工业出版社',
+                intro: '一本关于数据化运营的方法论书籍。',
                 category: '',
                 rating: '',
-                metadataReady: true,
+            },
+        ]);
+    });
+    it('rethrows AUTH_REQUIRED when search fallback finds the same title with a different visible author', async () => {
+        mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve({
+                books: [
+                    {
+                        bookInfo: {
+                            title: '文明',
+                            author: '作者乙',
+                            bookId: 'wrong-book',
+                        },
+                    },
+                ],
             }),
-            getCookies: vi.fn().mockResolvedValue([
-                { name: 'wr_vid', value: '70486028', domain: '.weread.qq.com' },
-            ]),
-            wait: vi.fn().mockResolvedValue(undefined),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            text: () => Promise.resolve(`
+          <ul class="search_bookDetail_list">
+            <li class="wr_bookList_item">
+              <a class="wr_bookList_item_link" href="/web/reader/wrong-reader"></a>
+              <p class="wr_bookList_item_title">文明</p>
+              <p class="wr_bookList_item_author">作者乙</p>
+            </li>
+          </ul>
+        `),
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const staleSnapshot = {
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'BOOK_1', title: '文明', author: '作者甲' },
+            ],
+            shelfIndexes: [
+                { bookId: 'stale-entry', idx: 0, role: 'book' },
+            ],
+        };
+        const page = createPageStub(...repeatValue(staleSnapshot, 2));
+        await expect(book.func(page, { 'book-id': 'BOOK_1' })).rejects.toMatchObject({
+            code: 'AUTH_REQUIRED',
+            message: 'Not logged in to WeRead',
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
+    });
+    it('falls back to raw cache order when shelf indexes never hydrate but rendered reader urls cover every cached entry', async () => {
+        mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network disabled')));
+        const emptyIndexSnapshot = {
+            cacheFound: true,
+            rawBooks: [
+                { bookId: '22920382', title: '数据化运营：系统方法与实践案例', author: '赵宏田 江丽萍 李宁' },
+                { bookId: 'MP_WXS_3634777637', title: '方伟看10年', author: '公众号' },
+            ],
+            shelfIndexes: [],
         };
+        const page = createPageStub(...repeatValue(emptyIndexSnapshot, 2), [
+            'https://weread.qq.com/web/reader/book229',
+            'https://weread.qq.com/web/reader/mp3634',
+        ], {
+            title: '方伟看10年',
+            author: '公众号',
+            publisher: '',
+            intro: '公众号文章详情。',
+            category: '',
+            rating: '',
+            metadataReady: true,
+        });
+        const result = await book.func(page, { 'book-id': 'MP_WXS_3634777637' });
+        expect(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
+        expect(page.goto).toHaveBeenNthCalledWith(2, 'https://weread.qq.com/web/reader/mp3634');
+        expect(result).toEqual([
+            {
+                title: '方伟看10年',
+                author: '公众号',
+                publisher: '',
+                intro: '公众号文章详情。',
+                category: '',
+                rating: '',
+            },
+        ]);
+    });
+    it('waits for shelf indexes to hydrate before resolving a trusted reader url', async () => {
+        mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
+        const page = createPageStub({
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
+                { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
+            ],
+            shelfIndexes: [
+                { bookId: 'BOOK_2', idx: 0, role: 'book' },
+            ],
+        }, {
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
+                { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
+            ],
+            shelfIndexes: [
+                { bookId: 'BOOK_2', idx: 0, role: 'book' },
+                { bookId: 'BOOK_1', idx: 1, role: 'book' },
+            ],
+        }, [
+            'https://weread.qq.com/web/reader/book2',
+            'https://weread.qq.com/web/reader/book1',
+        ], {
+            title: '第一本',
+            author: '作者甲',
+            publisher: '出版社甲',
+            intro: '简介甲',
+            category: '',
+            rating: '',
+            metadataReady: true,
+        });
         const result = await book.func(page, { 'book-id': 'BOOK_1' });
         expect(page.goto).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/shelf');
         expect(page.goto).toHaveBeenNthCalledWith(2, 'https://weread.qq.com/web/reader/book1');
@@ -212,35 +332,25 @@ describe('weread book-id positional args', () => {
     });
     it('rethrows AUTH_REQUIRED when the reader page lacks stable cover metadata', async () => {
         mockFetchPrivateApi.mockRejectedValue(new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first'));
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn()
-                .mockResolvedValueOnce({
-                cacheFound: true,
-                rawBooks: [
-                    { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
-                ],
-                shelfIndexes: [
-                    { bookId: 'BOOK_1', idx: 0, role: 'book' },
-                ],
-            })
-                .mockResolvedValueOnce([
-                'https://weread.qq.com/web/reader/book1',
-            ])
-                .mockResolvedValueOnce({
-                title: '',
-                author: '',
-                publisher: '',
-                intro: '这是正文第一段，不应该被当成简介。',
-                category: '',
-                rating: '',
-                metadataReady: false,
-            }),
-            getCookies: vi.fn().mockResolvedValue([
-                { name: 'wr_vid', value: '70486028', domain: '.weread.qq.com' },
-            ]),
-            wait: vi.fn().mockResolvedValue(undefined),
-        };
+        const page = createPageStub({
+            cacheFound: true,
+            rawBooks: [
+                { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
+            ],
+            shelfIndexes: [
+                { bookId: 'BOOK_1', idx: 0, role: 'book' },
+            ],
+        }, [
+            'https://weread.qq.com/web/reader/book1',
+        ], {
+            title: '',
+            author: '',
+            publisher: '',
+            intro: '这是正文第一段，不应该被当成简介。',
+            category: '',
+            rating: '',
+            metadataReady: false,
+        });
         await expect(book.func(page, { 'book-id': 'BOOK_1' })).rejects.toMatchObject({
             code: 'AUTH_REQUIRED',
             message: 'Not logged in to WeRead',

package/dist/clis/weread/utils.d.ts

@@ -31,6 +31,10 @@ export interface WebShelfEntry {
     author: string;
     readerUrl: string;
 }
+export interface WebShelfReaderResolution {
+    snapshot: WebShelfSnapshot;
+    readerUrl: string | null;
+}
 /**
  * Fetch a public WeRead web endpoint (Node.js direct fetch).
  * Used by search and ranking commands (browser: false).
@@ -62,5 +66,11 @@ export declare function loadWebShelfSnapshot(page: IPage): Promise<WebShelfSnaps
  * shelf cache order with the visible shelf links rendered on the page.
  */
 export declare function resolveShelfReaderUrl(page: IPage, bookId: string): Promise<string | null>;
+/**
+ * Resolve the current reader URL for a shelf entry and return the parsed shelf
+ * snapshot used during resolution, so callers can reuse cached title/author
+ * metadata without loading the shelf page twice.
+ */
+export declare function resolveShelfReader(page: IPage, bookId: string): Promise<WebShelfReaderResolution>;
 /** Format a Unix timestamp (seconds) to YYYY-MM-DD in UTC+8. Returns '-' for invalid input. */
 export declare function formatDate(ts: number | undefined | null): string;