@jackwener/opencli 1.7.21 → 1.8.0

package/clis/zhihu/answer-comments.test.js

@@ -0,0 +1,287 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './answer-comments.js';
+import { __test__ as helpers } from './answer-comments.js';
+
+describe('zhihu answer-comments', () => {
+    it('registers as a cookie read command', () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        expect(cmd).toBeDefined();
+        expect(cmd.access).toBe('read');
+        expect(cmd.strategy).toBe('cookie');
+    });
+
+    it('returns flattened comments while limiting only top-level comments', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const evaluate = vi.fn().mockImplementation(async (js) => {
+            expect(js).toContain('/api/v4/answers/2036567240334653053/comments?order=normal&limit=20');
+            expect(js).toContain("credentials: 'include'");
+            return {
+                data: [
+                    {
+                        id: 'c1',
+                        author: { member: { id: 'u1', name: 'alice' } },
+                        vote_count: 3,
+                        created_time: 1700000000,
+                        content: '<p>top &#34;one&#34;</p>',
+                    },
+                    {
+                        id: 'r1',
+                        author: { member: { id: 'u2', name: 'bob' } },
+                        reply_to_author: { member: { id: 'u1', name: 'alice' } },
+                        vote_count: 1,
+                        created_time: 1700000100,
+                        content: '<p>reply one</p>',
+                    },
+                    {
+                        id: 'r2',
+                        author: { member: { id: 'u3', name: 'carol' } },
+                        reply_to_author: { member: { id: 'u1', name: 'alice' } },
+                        vote_count: 2,
+                        created_time: 1700000200,
+                        content: '<p>reply two should be capped</p>',
+                    },
+                    {
+                        id: 'c2',
+                        author: { member: { id: 'u4', name: 'dave' } },
+                        vote_count: 4,
+                        created_time: 1700000300,
+                        content: '<p>top two</p>',
+                    },
+                    {
+                        id: 'c3',
+                        author: { member: { id: 'u5', name: 'erin' } },
+                        vote_count: 5,
+                        content: '<p>top three should stop the page walk</p>',
+                    },
+                ],
+                paging: { is_end: false, next: 'https://www.zhihu.com/api/v4/answers/2036567240334653053/comments?offset=20' },
+            };
+        });
+        const page = {
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('https://www.zhihu.com/question/2022852734622114542/answer/2036567240334653053'),
+            evaluate,
+        };
+        await expect(cmd.func(page, {
+            id: 'https://www.zhihu.com/question/2022852734622114542/answer/2036567240334653053',
+            limit: 2,
+            'replies-limit': 1,
+        })).resolves.toEqual([
+            {
+                rank: 1,
+                comment_rank: 1,
+                reply_rank: 0,
+                depth: 0,
+                id: 'c1',
+                parent_id: '',
+                author: 'alice',
+                reply_to: '',
+                likes: 3,
+                created_at: '2023-11-14T22:13:20.000Z',
+                url: 'https://www.zhihu.com/question/2022852734622114542/answer/2036567240334653053#comment-c1',
+                content: 'top "one"',
+            },
+            {
+                rank: 2,
+                comment_rank: 1,
+                reply_rank: 1,
+                depth: 0,
+                id: 'r1',
+                parent_id: '',
+                author: 'bob',
+                reply_to: 'alice',
+                likes: 1,
+                created_at: '2023-11-14T22:15:00.000Z',
+                url: 'https://www.zhihu.com/question/2022852734622114542/answer/2036567240334653053#comment-r1',
+                content: 'reply one',
+            },
+            {
+                rank: 3,
+                comment_rank: 2,
+                reply_rank: 0,
+                depth: 0,
+                id: 'c2',
+                parent_id: '',
+                author: 'dave',
+                reply_to: '',
+                likes: 4,
+                created_at: '2023-11-14T22:18:20.000Z',
+                url: 'https://www.zhihu.com/question/2022852734622114542/answer/2036567240334653053#comment-c2',
+                content: 'top two',
+            },
+        ]);
+        expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/answer/2036567240334653053');
+        expect(evaluate).toHaveBeenCalledTimes(1);
+    });
+
+    it('follows paging.next until enough top-level comments are collected', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const evaluate = vi.fn()
+            .mockResolvedValueOnce({
+                data: [
+                    { id: 'c1', author: { member: { id: 'u1', name: 'alice' } }, content: 'first' },
+                    { id: 'r1', author: { member: { id: 'u2', name: 'bob' } }, reply_to_author: { member: { id: 'u1', name: 'alice' } }, content: 'reply' },
+                ],
+                paging: { is_end: false, next: 'https://www.zhihu.com/api/v4/answers/1/comments?offset=20' },
+            })
+            .mockResolvedValueOnce({
+                data: [
+                    { id: 'c2', author: { member: { id: 'u3', name: 'carol' } }, content: 'second' },
+                ],
+                paging: { is_end: true },
+            });
+        const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+        const rows = await cmd.func(page, { id: '1', limit: 2, 'replies-limit': 0 });
+        expect(rows.map((row) => row.id)).toEqual(['c1', 'c2']);
+        expect(evaluate).toHaveBeenCalledTimes(2);
+        expect(evaluate.mock.calls[1][0]).toContain('offset=20');
+    });
+
+    it('supports typed answer targets', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [
+                    { id: 'c1', author: { member: { id: 'u1', name: 'alice' } }, content: 'typed target comment' },
+                ],
+                paging: { is_end: true },
+            }),
+        };
+        await expect(cmd.func(page, { id: 'answer:2022852734622114542:2036567240334653053', limit: 1, 'replies-limit': 0 }))
+            .resolves.toMatchObject([{ id: 'c1', url: 'https://www.zhihu.com/question/2022852734622114542/answer/2036567240334653053#comment-c1' }]);
+        expect(page.goto).toHaveBeenCalledWith('https://www.zhihu.com/answer/2036567240334653053');
+    });
+
+    it('maps auth failures to AuthRequiredError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 403 }),
+        };
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': 0 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('maps 404 not found to EmptyResultError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 404 }),
+        };
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': 0 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('maps malformed responses to CommandExecutionError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ data: {} }),
+        };
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps valid empty comments to EmptyResultError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ data: [], paging: { is_end: true } }),
+        };
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': 0 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('rejects malformed pagination next URLs and repeated next URLs', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const malformedNextPage = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [{ id: 'c1', author: { member: { id: 'u1', name: 'alice' } }, content: 'first' }],
+                paging: { is_end: false, next: 'https://evil.example/api/v4/answers/1/comments?offset=20' },
+            }),
+        };
+        await expect(cmd.func(malformedNextPage, { id: '1', limit: 2, 'replies-limit': 0 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+
+        const repeatedNextPage = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [{ id: 'c1', author: { member: { id: 'u1', name: 'alice' } }, content: 'first' }],
+                paging: { is_end: false, next: 'https://www.zhihu.com/api/v4/answers/1/comments?order=normal&limit=20&offset=0&status=open' },
+            }),
+        };
+        await expect(cmd.func(repeatedNextPage, { id: '1', limit: 2, 'replies-limit': 0 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects comment rows without stable comment id anchors', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [{ author: { member: { id: 'u1', name: 'alice' } }, content: 'missing id' }],
+                paging: { is_end: true },
+            }),
+        };
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects null comment items and non-primitive comment ids', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const basePage = (data) => ({
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ data, paging: { is_end: true } }),
+        });
+        await expect(cmd.func(basePage([null]), { id: '1', limit: 1, 'replies-limit': 0 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(cmd.func(basePage([{ id: { value: 'c1' }, content: 'object id' }]), { id: '1', limit: 1, 'replies-limit': 0 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(cmd.func(basePage([{ id: true, content: 'boolean id' }]), { id: '1', limit: 1, 'replies-limit': 0 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects invalid inputs before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/answer-comments');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: 'not-an-answer', limit: 1, 'replies-limit': 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { id: '1', limit: 0, 'replies-limit': 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { id: '1', limit: 1001, 'replies-limit': 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': -1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { id: '1', limit: 1, 'replies-limit': 101 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});
+
+describe('zhihu answer-comments helpers', () => {
+    it('parseAnswerTarget handles exact input shapes', () => {
+        expect(helpers.parseAnswerTarget('123')).toEqual({ answerId: '123', questionId: '' });
+        expect(helpers.parseAnswerTarget('answer:10:123')).toEqual({ answerId: '123', questionId: '10' });
+        expect(helpers.parseAnswerTarget('https://www.zhihu.com/question/10/answer/123')).toEqual({ answerId: '123', questionId: '10' });
+        expect(helpers.parseAnswerTarget('https://zhihu.com/answer/123?utm=1')).toEqual({ answerId: '123', questionId: '' });
+        expect(helpers.parseAnswerTarget('https://example.com/question/10/answer/123')).toBeNull();
+    });
+
+    it('normalizeCommentsApiUrl only accepts same-answer Zhihu comments API URLs', () => {
+        expect(helpers.normalizeCommentsApiUrl('https://www.zhihu.com/api/v4/answers/123/comments?offset=20', '123'))
+            .toBe('https://www.zhihu.com/api/v4/answers/123/comments?offset=20');
+        expect(helpers.normalizeCommentsApiUrl('https://api.zhihu.com/answers/123/comments?offset=20', '123'))
+            .toBe('https://www.zhihu.com/api/v4/answers/123/comments?offset=20');
+        expect(helpers.normalizeCommentsApiUrl('https://www.zhihu.com/api/v4/answers/999/comments?offset=20', '123')).toBe('');
+        expect(helpers.normalizeCommentsApiUrl('https://evil.example/api/v4/answers/123/comments?offset=20', '123')).toBe('');
+    });
+
+    it('buildRows keeps replies flat without guessing parent comment ids', () => {
+        const rows = helpers.buildRows([
+            { id: 'c1', author: { member: { id: 'u1', name: 'alice' } }, content: 'top' },
+            { id: 'r1', author: { member: { id: 'u2', name: 'bob' } }, reply_to_author: { member: { id: 'u1', name: 'alice' } }, content: 'reply' },
+            { id: 'r2', author: { member: { id: 'u3', name: 'carol' } }, reply_to_author: { member: { id: 'u2', name: 'bob' } }, content: 'nested' },
+        ], { answerId: 'a1', questionId: 'q1', topLevelLimit: 1, repliesLimit: 5 }).rows;
+        expect(rows.map((row) => [row.id, row.parent_id, row.depth, row.comment_rank, row.reply_rank])).toEqual([
+            ['c1', '', 0, 1, 0],
+            ['r1', '', 0, 1, 1],
+            ['r2', '', 0, 1, 2],
+        ]);
+    });
+});

package/clis/zhihu/answer-detail.js

@@ -19,6 +19,18 @@ function stripHtml(html) {
         .replace(/&/g, '&')
         .replace(/"/g, '"')
         .replace(/'/g, "'")
+        .replace(/&#(\d+);/g, (_, value) => {
+            const codePoint = Number(value);
+            return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10FFFF
+                ? String.fromCodePoint(codePoint)
+                : _;
+        })
+        .replace(/&#x([0-9a-f]+);/gi, (_, value) => {
+            const codePoint = Number.parseInt(value, 16);
+            return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10FFFF
+                ? String.fromCodePoint(codePoint)
+                : _;
+        })
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }

package/clis/zhihu/answer-detail.test.js

@@ -304,6 +304,14 @@ describe('zhihu answer-detail helpers', () => {
         expect(out).toBe('hi there & you\n\nsecond');
     });
 
+    it('stripHtml decodes numeric entities', () => {
+        expect(helpers.stripHtml('"中文" & 'test'')).toBe('"中文" & \'test\'');
+    });
+
+    it('stripHtml keeps invalid numeric entities unchanged', () => {
+        expect(helpers.stripHtml('bad � entity')).toBe('bad � entity');
+    });
+
     it('stripHtml maps <br> to single newline', () => {
         expect(helpers.stripHtml('a<br>b<br/>c')).toBe('a\nb\nc');
     });

package/clis/zhihu/collection.js

@@ -56,12 +56,18 @@ async function fetchCollectionPage(page, collectionId, offset, limit) {
 
 function itemKey(item) {
   const content = item?.content || {};
-  return `${content.type || 'unknown'}:${content.id || content.url || JSON.stringify(content).slice(0, 80)}`;
+  return `${content.type || ''}:${content.id || content.url || JSON.stringify(content).slice(0, 80)}`;
 }
 
 function mapCollectionItem(item, rank) {
   const content = item.content || {};
-  const type = content.type || 'unknown';
+  const type = content.type || '';
+  if (!['answer', 'article', 'pin'].includes(type)) {
+    throw new CommandExecutionError(
+      `Zhihu collection returned unsupported content type: ${type || 'missing'}`,
+      'Collection items require a supported content.type so the row identity, title, and URL are not silently blank.',
+    );
+  }
 
   let title = '';
   let excerpt = '';
@@ -90,6 +96,13 @@ function mapCollectionItem(item, rank) {
     votes = content.reaction_count || 0;
   }
 
+  if (!String(title || '').trim() || !String(url || '').trim() || url.includes('undefined')) {
+    throw new CommandExecutionError(
+      'Zhihu collection returned a malformed item without title or URL identity',
+      'Collection item rows require type, title, and URL so malformed payloads do not become blank listing rows.',
+    );
+  }
+
   return {
     rank,
     type,

package/clis/zhihu/collection.test.js

@@ -287,4 +287,50 @@ describe('zhihu collection', () => {
     await expect(cmd.func(page, { id: '83283292', offset: 0, limit: 20 }))
       .rejects.toBeInstanceOf(EmptyResultError);
   });
+
+  it('fails typed for missing content.type instead of emitting a blank identity row', async () => {
+    const cmd = getRegistry().get('zhihu/collection');
+    const evaluate = vi.fn().mockResolvedValue({
+      data: [
+        {
+          content: {
+            id: 555,
+            question: { id: 666, title: 'No-type Question' },
+            author: { name: 'a' },
+            voteup_count: 1,
+            content: '<p>x</p>',
+            url: 'https://www.zhihu.com/question/666',
+          },
+        },
+      ],
+      paging: { totals: 1 },
+    });
+    const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+    await expect(cmd.func(page, { id: '83283292', offset: 0, limit: 20 }))
+      .rejects.toBeInstanceOf(CommandExecutionError);
+  });
+
+  it('fails typed for supported collection items missing title/url identity', async () => {
+    const cmd = getRegistry().get('zhihu/collection');
+    const page = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn().mockResolvedValue({
+        data: [
+          {
+            content: {
+              type: 'answer',
+              id: 555,
+              question: { id: 666, title: '' },
+              author: { name: 'a' },
+              voteup_count: 1,
+              content: '<p>x</p>',
+            },
+          },
+        ],
+        paging: { totals: 1 },
+      }),
+    };
+    await expect(cmd.func(page, { id: '83283292', offset: 0, limit: 20 }))
+      .rejects.toBeInstanceOf(CommandExecutionError);
+  });
 });

package/clis/zhihu/download.js

@@ -41,7 +41,7 @@ cli({
 
         // Get author
         const authorEl = document.querySelector('.AuthorInfo-name, .UserLink-link');
-        result.author = authorEl?.textContent?.trim() || 'unknown';
+        result.author = authorEl?.textContent?.trim() || '';
 
         // Get publish time
         const timeEl = document.querySelector('.ContentItem-time, .Post-Time');

package/clis/zhihu/question.js

@@ -10,6 +10,34 @@ function stripHtml(html) {
         .trim();
 }
 
+function answerIdFromUrl(url) {
+    if (typeof url !== 'string') return '';
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname !== 'www.zhihu.com' && parsed.hostname !== 'zhihu.com') return '';
+        return parsed.pathname.match(/^\/question\/\d+\/answer\/(\d+)\/?$/)?.[1]
+            || parsed.pathname.match(/^\/api\/v4\/answers\/(\d+)\/?$/)?.[1]
+            || parsed.pathname.match(/^\/answer\/(\d+)\/?$/)?.[1]
+            || '';
+    } catch {
+        return '';
+    }
+}
+
+function answerId(item) {
+    const fromUrl = answerIdFromUrl(item.url);
+    if (fromUrl) return fromUrl;
+    if (typeof item.id === 'string' && /^\d+$/.test(item.id)) return item.id;
+    if (typeof item.id === 'number' && Number.isSafeInteger(item.id) && item.id > 0) return String(item.id);
+    return '';
+}
+
+function answerDedupeKey(item) {
+    const id = answerId(item);
+    if (id) return `id:${id}`;
+    return `fallback:${item.author?.name || 'anonymous'}:${item.content || ''}`;
+}
+
 const MAX_LIMIT = 1000;
 
 cli({
@@ -24,7 +52,7 @@ cli({
         { name: 'limit', type: 'int', default: 5, help: 'Number of answers (max 1000; use normal-sized requests)' },
         { name: 'sort', default: 'default', choices: ['default', 'created'], help: 'Answer order: default or created' },
     ],
-    columns: ['rank', 'author', 'votes', 'content'],
+    columns: ['rank', 'id', 'author', 'votes', 'url', 'content'],
     func: async (page, kwargs) => {
         const { id, limit = 5 } = kwargs;
         const questionId = String(id);
@@ -48,7 +76,7 @@ cli({
         // costs one over-fetched page worth of bandwidth and never silently
         // clamps the user-requested count.
         const ZHIHU_PAGE_SIZE = 20;
-        let url = `https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${ZHIHU_PAGE_SIZE}&offset=0&sort_by=${sort}&include=data[*].content,voteup_count,comment_count,author`;
+        let url = `https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${ZHIHU_PAGE_SIZE}&offset=0&sort_by=${sort}&include=data[*].content,url,voteup_count,comment_count,author`;
         const answers = [];
         const seen = new Set();
         const visited = new Set();
@@ -69,7 +97,7 @@ cli({
                 throw new CliError('FETCH_ERROR', status ? `Zhihu question answers request failed (HTTP ${status})` : 'Zhihu question answers request failed', 'Try again later or rerun with -v for more detail');
             }
             for (const item of data.data || []) {
-                const key = item.id == null ? `${item.author?.name || 'anonymous'}:${item.content || ''}` : String(item.id);
+                const key = answerDedupeKey(item);
                 if (seen.has(key)) continue;
                 seen.add(key);
                 answers.push(item);
@@ -78,11 +106,16 @@ cli({
             if (data.paging?.is_end) break;
             url = typeof data.paging?.next === 'string' ? data.paging.next : '';
         }
-        return answers.map((item, i) => ({
-            rank: i + 1,
-            author: item.author?.name || 'anonymous',
-            votes: item.voteup_count || 0,
-            content: stripHtml(item.content || '').substring(0, 200),
-        }));
+        return answers.map((item, i) => {
+            const id = answerId(item);
+            return {
+                rank: i + 1,
+                id,
+                author: item.author?.name || 'anonymous',
+                votes: item.voteup_count || 0,
+                url: id ? `https://www.zhihu.com/question/${questionId}/answer/${id}` : '',
+                content: stripHtml(item.content || '').substring(0, 200),
+            };
+        });
     },
 });