@jackwener/opencli 1.7.7 → 1.7.9

package/clis/zhihu/follow.test.js

@@ -2,44 +2,41 @@ import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 import './follow.js';
 describe('zhihu follow', () => {
-    it('rejects missing --execute before any browser write path', async () => {
+    it('registers as a cookie browser command', () => {
         const cmd = getRegistry().get('zhihu/follow');
-        expect(cmd?.func).toBeTypeOf('function');
-        const page = { goto: vi.fn(), evaluate: vi.fn() };
-        await expect(cmd.func(page, { target: 'question:123' })).rejects.toMatchObject({ code: 'INVALID_INPUT' });
-        expect(page.goto).not.toHaveBeenCalled();
-        expect(page.evaluate).not.toHaveBeenCalled();
+        expect(cmd).toBeDefined();
+        expect(cmd.strategy).toBe('cookie');
     });
-    it('rejects user pages where the primary follow control is not uniquely anchored', async () => {
+    it('follows via API and returns result', async () => {
         const cmd = getRegistry().get('zhihu/follow');
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'ambiguous_user_follow' }),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValueOnce({ ok: true }),
         };
-        await expect(cmd.func(page, { target: 'user:alice', execute: true })).rejects.toMatchObject({
-            code: 'ACTION_NOT_AVAILABLE',
-        });
+        const rows = await cmd.func(page, { target: 'question:123', execute: true });
+        expect(rows).toEqual([expect.objectContaining({ outcome: 'applied' })]);
     });
-    it('returns already_applied when already following', async () => {
+    it('uses the parsed user slug for user follow API calls', async () => {
         const cmd = getRegistry().get('zhihu/follow');
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'already_following' }),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValueOnce({ ok: true }),
         };
-        await expect(cmd.func(page, { target: 'question:123', execute: true })).resolves.toEqual([
-            expect.objectContaining({ outcome: 'already_applied', target_type: 'question', target: 'question:123' }),
-        ]);
+        await cmd.func(page, { target: 'user:alice', execute: true });
+        expect(page.evaluate.mock.calls[0][0]).toContain("'https://www.zhihu.com/api/v4/members/' + targetId + '/followers'");
+        expect(page.evaluate.mock.calls[0][0]).toContain('var targetId = "alice"');
+        expect(page.evaluate.mock.calls[0][0]).not.toContain('undefined');
     });
-    it('rejects question pages where the question follow control is not uniquely anchored', async () => {
+    it('throws on API error', async () => {
         const cmd = getRegistry().get('zhihu/follow');
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'ambiguous_question_follow' }),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValueOnce({ ok: false, message: 'already following' }),
         };
-        await expect(cmd.func(page, { target: 'question:123', execute: true })).rejects.toMatchObject({
-            code: 'ACTION_NOT_AVAILABLE',
-        });
-        expect(page.evaluate.mock.calls[0][0]).toContain('QuestionHeader');
-        expect(page.evaluate.mock.calls[0][0]).toContain('new Set(');
+        await expect(cmd.func(page, { target: 'question:123', execute: true }))
+            .rejects.toMatchObject({ code: 'COMMAND_EXEC' });
     });
 });

package/clis/zhihu/like.js

@@ -7,7 +7,7 @@ cli({
     name: 'like',
     description: 'Like a Zhihu answer or article',
     domain: 'zhihu.com',
-    strategy: Strategy.UI,
+    strategy: Strategy.COOKIE,
     browser: true,
     args: [
         { name: 'target', positional: true, required: true, help: 'Zhihu target URL or typed target' },
@@ -20,72 +20,27 @@ cli({
         requireExecute(kwargs);
         const rawTarget = String(kwargs.target);
         const target = assertAllowedKinds('like', parseTarget(rawTarget));
-        await page.goto(target.url);
-        const result = await page.evaluate(`(async () => {
-      const targetKind = ${JSON.stringify(target.kind)};
-      const targetQuestionId = ${JSON.stringify(target.kind === 'answer' ? target.questionId : null)};
-      const targetAnswerId = ${JSON.stringify(target.kind === 'answer' ? target.id : null)};
-
-      let btn = null;
-      if (targetKind === 'answer') {
-        const block = Array.from(document.querySelectorAll('article, .AnswerItem, [data-zop-question-answer]')).find((node) => {
-          const dataAnswerId = node.getAttribute('data-answerid') || node.getAttribute('data-zop-question-answer') || '';
-          if (dataAnswerId && dataAnswerId.includes(targetAnswerId)) return true;
-          return Array.from(node.querySelectorAll('a[href*="/answer/"]')).some((link) => {
-            const href = link.getAttribute('href') || '';
-            return href.includes('/question/' + targetQuestionId + '/answer/' + targetAnswerId);
-          });
-        });
-        if (!block) return { state: 'wrong_answer' };
-        const candidates = Array.from(block?.querySelectorAll('button') || []).filter((node) => {
-          const text = (node.textContent || '').trim();
-          const inCommentItem = Boolean(node.closest('[data-comment-id], .CommentItem'));
-          return /赞同|赞/.test(text) && node.hasAttribute('aria-pressed') && !inCommentItem;
-        });
-        if (candidates.length !== 1) return { state: 'ambiguous_answer_like' };
-        btn = candidates[0];
-      } else {
-        const articleRoot =
-          document.querySelector('article')
-          || document.querySelector('.Post-Main')
-          || document.querySelector('[itemprop="articleBody"]')
-          || document;
-        const candidates = Array.from(articleRoot.querySelectorAll('button')).filter((node) => {
-          const text = (node.textContent || '').trim();
-          return /赞同|赞/.test(text) && node.hasAttribute('aria-pressed');
-        });
-        if (candidates.length !== 1) return { state: 'ambiguous_article_like' };
-        btn = candidates[0];
-      }
-
-      if (!btn) return { state: 'missing' };
-      if (btn.getAttribute('aria-pressed') === 'true') return { state: 'already_liked' };
-
-      btn.click();
-      await new Promise((resolve) => setTimeout(resolve, 1200));
-
-      return btn.getAttribute('aria-pressed') === 'true'
-        ? { state: 'liked' }
-        : { state: 'unknown' };
-    })()`);
-        if (result?.state === 'wrong_answer') {
-            throw new CliError('TARGET_NOT_FOUND', 'Resolved answer target no longer matches the requested answer:<questionId>:<answerId>');
+        await page.goto('https://www.zhihu.com');
+        await page.wait(2);
+        const apiResult = await page.evaluate(`(async () => {
+            var targetKind = ${JSON.stringify(target.kind)};
+            var targetId = ${JSON.stringify(target.id)};
+            var resourceType = targetKind === 'answer' ? 'answers' : 'articles';
+            var url = 'https://www.zhihu.com/api/v4/' + resourceType + '/' + targetId + '/voters';
+            var resp = await fetch(url, {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'up' }),
+            });
+            var data = await resp.json();
+            if (!resp.ok) return { ok: false, message: data.error ? data.error.message : 'unknown error' };
+            if (data && data.success === false) return { ok: false, message: 'Zhihu like API reported success=false' };
+            return { ok: true, success: data.success };
+        })()`);
+        if (!apiResult?.ok) {
+            throw new CliError('COMMAND_EXEC', apiResult?.message || 'Failed to like');
         }
-        if (result?.state === 'already_liked') {
-            return buildResultRow(`Already liked ${target.kind}`, target.kind, rawTarget, 'already_applied');
-        }
-        if (result?.state === 'ambiguous_answer_like') {
-            throw new CliError('ACTION_NOT_AVAILABLE', 'Answer like control was not uniquely anchored on the requested answer');
-        }
-        if (result?.state === 'ambiguous_article_like') {
-            throw new CliError('ACTION_NOT_AVAILABLE', 'Article like control was not uniquely anchored on the requested target');
-        }
-        if (result?.state === 'missing') {
-            throw new CliError('ACTION_FAILED', 'Zhihu like control was missing before any write was dispatched');
-        }
-        if (result?.state !== 'liked') {
-            throw new CliError('OUTCOME_UNKNOWN', 'Zhihu like click was dispatched, but the final state could not be verified safely');
-        }
-        return buildResultRow(`Liked ${target.kind}`, target.kind, rawTarget, 'applied');
+        return buildResultRow(`Liked ${target.kind} ${target.id}`, target.kind, rawTarget, 'applied');
     },
 });

package/clis/zhihu/like.test.js

@@ -2,63 +2,40 @@ import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 import './like.js';
 describe('zhihu like', () => {
-    it('rejects article pages where the like control is not uniquely anchored', async () => {
+    it('registers as a cookie browser command', () => {
         const cmd = getRegistry().get('zhihu/like');
-        expect(cmd?.func).toBeTypeOf('function');
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'ambiguous_article_like' }),
-        };
-        await expect(cmd.func(page, { target: 'article:9', execute: true })).rejects.toMatchObject({
-            code: 'ACTION_NOT_AVAILABLE',
-        });
-    });
-    it('returns already_applied for an already-liked article target', async () => {
-        const cmd = getRegistry().get('zhihu/like');
-        const page = {
-            goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'already_liked' }),
-        };
-        await expect(cmd.func(page, { target: 'article:9', execute: true })).resolves.toEqual([
-            expect.objectContaining({ outcome: 'already_applied', target_type: 'article', target: 'article:9' }),
-        ]);
+        expect(cmd).toBeDefined();
+        expect(cmd.strategy).toBe('cookie');
     });
-    it('anchors to the requested answer block before clicking like', async () => {
+    it('likes via API and returns result', async () => {
         const cmd = getRegistry().get('zhihu/like');
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'liked' }),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValueOnce({ ok: true, success: true }),
         };
-        await expect(cmd.func(page, { target: 'answer:123:456', execute: true })).resolves.toEqual([
-            expect.objectContaining({ outcome: 'applied', target_type: 'answer', target: 'answer:123:456' }),
-        ]);
-        expect(page.goto).toHaveBeenCalledWith('https://www.zhihu.com/question/123/answer/456');
-        expect(page.evaluate).toHaveBeenCalledTimes(1);
-        expect(page.evaluate.mock.calls[0][0]).toContain('targetQuestionId');
-        expect(page.evaluate.mock.calls[0][0]).toContain('"123"');
-        expect(page.evaluate.mock.calls[0][0]).toContain('"456"');
-        expect(page.evaluate.mock.calls[0][0]).toContain("node.getAttribute('data-answerid')");
-        expect(page.evaluate.mock.calls[0][0]).toContain("node.getAttribute('data-zop-question-answer')");
+        const rows = await cmd.func(page, { target: 'answer:1:2', execute: true });
+        expect(rows).toEqual([expect.objectContaining({ outcome: 'applied' })]);
     });
-    it('rejects answer targets when the answer-level like control is not unique', async () => {
+    it('throws on API error', async () => {
         const cmd = getRegistry().get('zhihu/like');
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'ambiguous_answer_like' }),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValueOnce({ ok: false, message: 'rate limited' }),
         };
-        await expect(cmd.func(page, { target: 'answer:123:456', execute: true })).rejects.toMatchObject({
-            code: 'ACTION_NOT_AVAILABLE',
-        });
+        await expect(cmd.func(page, { target: 'answer:1:2', execute: true }))
+            .rejects.toMatchObject({ code: 'COMMAND_EXEC' });
     });
-    it('maps missing answer blocks to TARGET_NOT_FOUND', async () => {
+    it('does not treat success=false API responses as a successful like', async () => {
         const cmd = getRegistry().get('zhihu/like');
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),
-            evaluate: vi.fn().mockResolvedValue({ state: 'wrong_answer' }),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValueOnce({ ok: false, message: 'Zhihu like API reported success=false' }),
         };
-        await expect(cmd.func(page, { target: 'answer:123:456', execute: true })).rejects.toMatchObject({
-            code: 'TARGET_NOT_FOUND',
-        });
-        expect(page.evaluate.mock.calls[0][0]).toContain("if (!block) return { state: 'wrong_answer' }");
+        await expect(cmd.func(page, { target: 'answer:1:2', execute: true }))
+            .rejects.toMatchObject({ code: 'COMMAND_EXEC' });
+        expect(page.evaluate.mock.calls[0][0]).toContain('data.success === false');
     });
 });

package/clis/zhihu/search.js

@@ -15,12 +15,13 @@ cli({
   const strip = (html) => (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/<em>/g, '').replace(/<\\/em>/g, '').trim();
   const keyword = \${{ args.query | json }};
   const limit = \${{ args.limit }};
-  const res = await fetch('https://www.zhihu.com/api/v4/search_v3?q=' + encodeURIComponent(keyword) + '&t=general&offset=0&limit=' + limit, {
+  var fetchLimit = Math.max(limit * 3, 30);
+  const res = await fetch('https://www.zhihu.com/api/v4/search_v3?q=' + encodeURIComponent(keyword) + '&t=general&offset=0&limit=' + fetchLimit, {
     credentials: 'include'
   });
   const d = await res.json();
   return (d?.data || [])
-    .filter(item => item.type === 'search_result')
+    .filter(item => item.object && (item.object.type === 'answer' || item.object.type === 'article' || item.object.type === 'question'))
     .map(item => {
       const obj = item.object || {};
       const q = obj.question || {};

package/clis/zhihu/write-shared.js

@@ -194,7 +194,14 @@ function buildResolveCurrentUserIdentityJs() {
 
     const navScopes = Array.from(document.querySelectorAll(navScopeSelector));
     const slug = findCurrentUserSlugFromRoots(navScopes, true) || findCurrentUserSlugFromRoots([document], false);
-    return slug ? { slug } : null;
+    if (slug) return { slug };
+
+    var avatarImgs = document.querySelectorAll('header img[alt*="\\u4e3b\\u9875"]');
+    for (var ai = 0; ai < avatarImgs.length; ai++) {
+      var altMatch = (avatarImgs[ai].alt || '').match(/\\u70b9\\u51fb\\u6253\\u5f00(.+?)\\u7684\\u4e3b\\u9875/);
+      if (altMatch) return { slug: altMatch[1] };
+    }
+    return null;
   })()`;
 }
 export async function resolveCurrentUserIdentity(page) {

package/clis/zhihu/write-shared.test.js

@@ -163,6 +163,7 @@ describe('zhihu write shared helpers', () => {
         const documentRoot = new FakeRoot({
             'header, nav, [role="banner"], [role="navigation"]': [],
             'a[href^="/people/"]': [],
+            'header img[alt*="\u4e3b\u9875"]': [],
         });
         const page = createPageForDom(documentRoot);
         await expect(__test__.resolveCurrentUserIdentity(page)).rejects.toMatchObject({

package/clis/zlibrary/commands.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import {
+  buildSearchUrl,
+  normalizeZlibraryBookUrl,
+} from './utils.js';
+import './search.js';
+import './info.js';
+
+function createPageMock(evaluateResults = []) {
+  const evaluate = vi.fn();
+  for (const result of evaluateResults) {
+    evaluate.mockResolvedValueOnce(result);
+  }
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate,
+  };
+}
+
+describe('zlibrary commands', () => {
+  it('registers search and info commands', () => {
+    expect(getRegistry().get('zlibrary/search')).toBeDefined();
+    expect(getRegistry().get('zlibrary/info')).toBeDefined();
+  });
+
+  it('normalizes search query and rejects empty searches', () => {
+    expect(buildSearchUrl('  test book  ')).toBe('https://z-library.im/s/test%20book');
+    expect(() => buildSearchUrl('   ')).toThrow(ArgumentError);
+  });
+
+  it('restricts info URLs to the configured zlibrary host', () => {
+    expect(normalizeZlibraryBookUrl('https://z-library.im/book/demo')).toBe('https://z-library.im/book/demo');
+    expect(normalizeZlibraryBookUrl('https://www.z-library.im/book/demo')).toBe('https://www.z-library.im/book/demo');
+    expect(() => normalizeZlibraryBookUrl('https://example.com/book/demo')).toThrow(ArgumentError);
+  });
+
+  it('search fails fast on empty extraction results', async () => {
+    const command = getRegistry().get('zlibrary/search');
+    const page = createPageMock(['[]']);
+
+    await expect(command.func(page, { query: 'missing', limit: 10 })).rejects.toBeInstanceOf(EmptyResultError);
+  });
+
+  it('info waits seconds, not milliseconds-as-seconds, before extracting formats', async () => {
+    const command = getRegistry().get('zlibrary/info');
+    const page = createPageMock([
+      'Demo Book',
+      undefined,
+      JSON.stringify({ pdf: 'https://z-library.im/dl/pdf', epub: '' }),
+    ]);
+
+    await expect(command.func(page, { url: 'https://z-library.im/book/demo' })).resolves.toEqual([{
+      title: 'Demo Book',
+      pdf: 'https://z-library.im/dl/pdf',
+      epub: '',
+      url: 'https://z-library.im/book/demo',
+    }]);
+    expect(page.wait).toHaveBeenCalledWith({ time: 5 });
+    expect(page.wait).toHaveBeenCalledWith({ time: 3 });
+  });
+
+  it('info fails fast when formats are missing', async () => {
+    const command = getRegistry().get('zlibrary/info');
+    const page = createPageMock([
+      'Login Required',
+      undefined,
+      JSON.stringify({ pdf: '', epub: '' }),
+    ]);
+
+    await expect(command.func(page, { url: 'https://z-library.im/book/demo' })).rejects.toBeInstanceOf(EmptyResultError);
+  });
+});

package/clis/zlibrary/info.js

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { ZLIBRARY_DOMAIN, extractBookTitle, extractFormats, normalizeZlibraryBookUrl } from './utils.js';
+
+cli({
+  site: 'zlibrary',
+  name: 'info',
+  description: 'Get book details and available download formats from a Z-Library book page',
+  domain: ZLIBRARY_DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'url',
+      positional: true,
+      required: true,
+      help: 'Z-Library book page URL (e.g. https://z-library.im/book/...)',
+    },
+  ],
+  columns: ['title', 'pdf', 'epub', 'url'],
+  func: async (page, args) => {
+    const url = normalizeZlibraryBookUrl(args.url);
+
+    await page.goto(url, { waitUntil: 'load', settleMs: 3000 });
+    await page.wait({ time: 5 });
+
+    const title = await extractBookTitle(page);
+    const formats = await extractFormats(page);
+
+    if (!title || (!formats.pdf && !formats.epub)) {
+      throw new EmptyResultError(
+        'zlibrary info',
+        'Could not extract a book title and download formats. Check the URL, login state, and whether Z-Library changed its page layout.',
+      );
+    }
+
+    return [
+      {
+        title,
+        pdf: formats.pdf || '',
+        epub: formats.epub || '',
+        url,
+      },
+    ];
+  },
+});

package/clis/zlibrary/search.js

@@ -0,0 +1,46 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { ZLIBRARY_DOMAIN, buildSearchUrl, extractSearchResults } from './utils.js';
+
+cli({
+  site: 'zlibrary',
+  name: 'search',
+  description: 'Search Z-Library for books by title, author, ISBN, or keyword',
+  domain: ZLIBRARY_DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'query',
+      positional: true,
+      required: true,
+      help: 'Search keyword (title, author, ISBN, etc.)',
+    },
+    {
+      name: 'limit',
+      type: 'int',
+      default: 10,
+      help: 'Max results (1–25)',
+    },
+  ],
+  columns: ['rank', 'title', 'author', 'url'],
+  func: async (page, args) => {
+    const limit = Math.max(1, Math.min(Number(args.limit) || 10, 25));
+    const searchUrl = buildSearchUrl(args.query);
+
+    await page.goto(searchUrl, { waitUntil: 'load', settleMs: 3000 });
+    await page.wait({ time: 5 });
+
+    const results = await extractSearchResults(page, limit);
+
+    if (!results.length) {
+      throw new EmptyResultError(
+        'zlibrary search',
+        'No books found. Try a different keyword or check that you are logged into Z-Library.',
+      );
+    }
+
+    return results;
+  },
+});

package/clis/zlibrary/utils.js

@@ -0,0 +1,136 @@
+/**
+ * Z-Library adapter utilities.
+ */
+
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+const ZLIBRARY_DOMAIN = 'z-library.im';
+const ZLIBRARY_ORIGIN = `https://${ZLIBRARY_DOMAIN}`;
+const ZLIBRARY_ALLOWED_HOSTS = new Set([
+  ZLIBRARY_DOMAIN,
+  `www.${ZLIBRARY_DOMAIN}`,
+]);
+
+export function normalizeZlibraryBookUrl(input) {
+  const raw = String(input || '').trim();
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ArgumentError('Z-Library book URL must be a valid http(s) URL', `Example: ${ZLIBRARY_ORIGIN}/book/...`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol) || !ZLIBRARY_ALLOWED_HOSTS.has(url.hostname)) {
+    throw new ArgumentError(
+      `Unsupported Z-Library URL host: ${url.hostname}`,
+      `Pass a book URL under ${ZLIBRARY_DOMAIN}, for example ${ZLIBRARY_ORIGIN}/book/...`,
+    );
+  }
+  return url.toString();
+}
+
+/**
+ * Build a Z-Library search URL.
+ * Z-Library uses /s/<url-encoded-query> for search.
+ */
+export function buildSearchUrl(query) {
+  const normalized = String(query || '').trim();
+  if (!normalized) {
+    throw new ArgumentError('zlibrary search query cannot be empty');
+  }
+  return `${ZLIBRARY_ORIGIN}/s/${encodeURIComponent(normalized)}`;
+}
+
+/**
+ * Extract book title from page context.
+ * Tries z-bookcard shadow DOM first, then falls back to page title.
+ */
+export async function extractBookTitle(page) {
+  const title = await page.evaluate(`
+      (() => {
+        const card = document.querySelector('z-bookcard');
+        if (card && card.shadowRoot) {
+          const el = card.shadowRoot.querySelector('[class*="title"], h1, a');
+          if (el) return el.textContent.trim().split('\\n')[0].trim();
+        }
+        return document.title.replace(/\\s*[-|].*$/, '').trim();
+      })()
+    `);
+  return String(title || '').trim();
+}
+
+/**
+ * Extract available download formats from book page.
+ * Clicks the three-dot menu to reveal download options.
+ * NOTE: Z-Library download links redirect through /dl/<hash> URLs.
+ * These require browser cookies and may not produce direct file downloads
+ * in OpenCLI's browser automation. For actual file downloading,
+ * consider using Playwright's download event handling instead.
+ */
+export async function extractFormats(page) {
+  // Click three-dot menu if present
+  await page.evaluate(`
+      (() => {
+        const btn = document.querySelector(
+          'button[aria-label*="more" i], [class*="dots" i], [class*="more" i]'
+        );
+        if (btn) btn.click();
+      })()
+    `);
+  // Wait for menu
+  await page.wait({ time: 3 });
+
+  const formats = await page.evaluate(`
+      JSON.stringify((() => {
+        const res = { pdf: '', epub: '' };
+        document.querySelectorAll('a[href]').forEach(a => {
+          const h = a.href || '';
+          const t = (a.textContent || '').toUpperCase();
+          if (h.includes('/dl/') && t.includes('PDF')) res.pdf = h;
+          if (h.includes('/dl/') && t.includes('EPUB')) res.epub = h;
+        });
+        return res;
+      })())
+    `);
+  return JSON.parse(formats);
+}
+
+/**
+ * Extract book cards from search results page.
+ *
+ * Z-Library renders search results as <z-bookcard> custom elements.
+ * Each card contains the book title, author, and a link to the book page.
+ * The link is inside a shadow DOM that can be queried with card.shadowRoot.
+ *
+ * This approach was validated on 2026-04-28 against z-library.im.
+ */
+export async function extractSearchResults(page, limit) {
+  const raw = await page.evaluate(`
+    JSON.stringify(
+      Array.from(document.querySelectorAll('z-bookcard'))
+        .slice(0, ${limit})
+        .map((card, index) => {
+          const text = card.textContent.trim();
+          const lines = text.split('\\n').map(l => l.trim()).filter(Boolean);
+          const title = lines[0] || '';
+          const author = lines[1] || '';
+          let url = '';
+          try {
+            if (card.shadowRoot) {
+              const link = card.shadowRoot.querySelector('a');
+              if (link) url = link.href || '';
+            }
+          } catch(e) {}
+          return { rank: index + 1, title, author, url };
+        })
+        .filter(item => item.url && item.title)
+    )
+  `);
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return [];
+  }
+}
+
+export { ZLIBRARY_DOMAIN, ZLIBRARY_ORIGIN };

package/dist/src/adapter-source.d.ts

@@ -0,0 +1,11 @@
+import type { InternalCliCommand } from './registry.js';
+/**
+ * Resolve the editable source file path for an adapter.
+ *
+ * Priority:
+ * 1. cmd.source (set for FS-scanned JS and manifest lazy-loaded JS)
+ * 2. cmd._modulePath (set for manifest lazy-loaded JS)
+ *
+ * Skip manifest: prefixed pseudo-paths (YAML commands inlined in manifest).
+ */
+export declare function resolveAdapterSourcePath(cmd: InternalCliCommand): string | undefined;

package/dist/src/adapter-source.js

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs';
+/**
+ * Resolve the editable source file path for an adapter.
+ *
+ * Priority:
+ * 1. cmd.source (set for FS-scanned JS and manifest lazy-loaded JS)
+ * 2. cmd._modulePath (set for manifest lazy-loaded JS)
+ *
+ * Skip manifest: prefixed pseudo-paths (YAML commands inlined in manifest).
+ */
+export function resolveAdapterSourcePath(cmd) {
+    const candidates = [];
+    if (cmd.source && !cmd.source.startsWith('manifest:')) {
+        candidates.push(cmd.source);
+    }
+    if (cmd._modulePath) {
+        candidates.push(cmd._modulePath);
+    }
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0];
+}