@jackwener/opencli 1.7.20 → 1.7.21

package/clis/boss/chatmsg.test.js

@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './chatmsg.js';
+
+const BOSS_FRIEND = {
+    uid: 12345,
+    encryptUid: 'enc-boss-uid',
+    securityId: 'boss-sec-id',
+    name: '候选人甲',
+};
+const BOSS_MSGS = [
+    { type: 1, text: 'Hello', from: { uid: 99999, name: 'HR' }, time: 1704067200000 },
+    { type: 1, text: '感谢', from: { uid: 12345, name: '候选人甲' }, time: 1704067201000 },
+];
+
+const GEEK_FRIEND_LABEL = {
+    friendId: 11111,
+    encryptFriendId: 'enc-geek-uid',
+    name: 'Boss张',
+    brandName: '公司A',
+};
+const GEEK_FRIEND_ENRICHED = {
+    friendId: 11111,
+    uid: 67890,
+    encryptUid: 'enc-geek-uid',
+    securityId: 'geek-sec-id',
+    name: 'Boss张',
+};
+const GEEK_MSGS = [
+    { type: 1, text: '欢迎投递', received: true, time: 1704067200000, from: { uid: 67890, name: 'Boss张' } },
+    { type: 1, text: '谢谢', received: true, time: 1704067201000, from: { uid: 99999, name: '我' } },
+];
+
+function createPageMock(evaluateImpl) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockImplementation(evaluateImpl),
+    };
+}
+
+describe('boss chatmsg', () => {
+    const command = getRegistry().get('boss/chatmsg');
+
+    it('rejects empty uid before navigating', async () => {
+        const page = createPageMock(async () => ({}));
+        await expect(
+            command.func(page, { uid: ' ', page: 1, side: 'geek' })
+        ).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('rejects invalid --page before navigating', async () => {
+        const page = createPageMock(async () => ({}));
+        await expect(
+            command.func(page, { uid: 'enc-geek-uid', page: 0, side: 'geek' })
+        ).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('--side boss preserves existing behavior', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('getBossFriendListV2')) {
+                return { code: 0, zpData: { friendList: [BOSS_FRIEND] } };
+            }
+            if (script.includes('boss/historyMsg')) {
+                return { code: 0, zpData: { messages: BOSS_MSGS } };
+            }
+            return {};
+        });
+        const rows = await command.func(page, { uid: 'enc-boss-uid', page: 1, side: 'boss' });
+        expect(page.goto).toHaveBeenCalledWith(expect.stringContaining('/web/chat/index'));
+        expect(rows).toHaveLength(2);
+        expect(rows[0].from).toBe('我');
+        expect(rows[1].from).toBe('候选人甲');
+    });
+
+    it('--side geek calls historyMsg with bossId, securityId, page, c=20, src=0', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('document.cookie')) return 'test-enc-sys-id';
+            if (script.includes('geekFilterByLabel')) {
+                return { code: 0, zpData: { friendList: [GEEK_FRIEND_LABEL] } };
+            }
+            if (script.includes('getGeekFriendList.json')) {
+                return { code: 0, zpData: { result: [GEEK_FRIEND_ENRICHED] } };
+            }
+            if (script.includes('geek/historyMsg')) {
+                return { code: 0, zpData: { messages: GEEK_MSGS } };
+            }
+            return {};
+        });
+        await command.func(page, { uid: 'enc-geek-uid', page: 1, side: 'geek' });
+        const historyScript = page.evaluate.mock.calls.find((c) => c[0].includes('geek/historyMsg'))?.[0];
+        expect(historyScript).toBeDefined();
+        expect(historyScript).toContain('bossId=67890');
+        expect(historyScript).toContain('securityId=');
+        expect(historyScript).toContain('page=1');
+        expect(historyScript).toContain('c=20');
+        expect(historyScript).toContain('src=0');
+    });
+
+    it('--side geek uses from.uid to determine direction, not received flag', async () => {
+        // Both messages have received:true (mirrors real geek historyMsg API behaviour)
+        // Direction is determined by whether m.from.uid matches the boss's uid (67890)
+        const msgsAllReceived = [
+            { type: 1, text: '欢迎投递', received: true, time: 1704067200000, from: { uid: 67890, name: 'Boss张' } },
+            { type: 1, text: '谢谢', received: true, time: 1704067201000, from: { uid: 99999, name: '我' } },
+        ];
+        const page = createPageMock(async (script) => {
+            if (script.includes('document.cookie')) return 'test-enc-sys-id';
+            if (script.includes('geekFilterByLabel')) {
+                return { code: 0, zpData: { friendList: [GEEK_FRIEND_LABEL] } };
+            }
+            if (script.includes('getGeekFriendList.json')) {
+                return { code: 0, zpData: { result: [GEEK_FRIEND_ENRICHED] } };
+            }
+            if (script.includes('geek/historyMsg')) {
+                return { code: 0, zpData: { messages: msgsAllReceived } };
+            }
+            return {};
+        });
+        const rows = await command.func(page, { uid: 'enc-geek-uid', page: 1, side: 'geek' });
+        // from.uid=67890 matches friend.uid=67890 → boss sent it → '对方'
+        expect(rows[0].from).toBe('对方');
+        // from.uid=99999 does not match → geek sent it → '我'
+        expect(rows[1].from).toBe('我');
+    });
+
+    it('non-text message body does not crash and produces truncated JSON', async () => {
+        const nonTextMsg = { type: 99, received: true, time: 1704067200000, body: { action: 'resume_request', detail: 'X' } };
+        const page = createPageMock(async (script) => {
+            if (script.includes('document.cookie')) return 'test-enc-sys-id';
+            if (script.includes('geekFilterByLabel')) {
+                return { code: 0, zpData: { friendList: [GEEK_FRIEND_LABEL] } };
+            }
+            if (script.includes('getGeekFriendList.json')) {
+                return { code: 0, zpData: { result: [GEEK_FRIEND_ENRICHED] } };
+            }
+            if (script.includes('geek/historyMsg')) {
+                return { code: 0, zpData: { messages: [nonTextMsg] } };
+            }
+            return {};
+        });
+        const rows = await command.func(page, { uid: 'enc-geek-uid', page: 1, side: 'geek' });
+        expect(rows).toHaveLength(1);
+        expect(rows[0].text).toContain('resume_request');
+    });
+
+    it('--side auto falls back to geek when recruiter returns code 24', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('getBossFriendListV2')) {
+                return { code: 24, message: '请切换身份后再试' };
+            }
+            if (script.includes('document.cookie')) return 'test-enc-sys-id';
+            if (script.includes('geekFilterByLabel')) {
+                return { code: 0, zpData: { friendList: [GEEK_FRIEND_LABEL] } };
+            }
+            if (script.includes('getGeekFriendList.json')) {
+                return { code: 0, zpData: { result: [GEEK_FRIEND_ENRICHED] } };
+            }
+            if (script.includes('geek/historyMsg')) {
+                return { code: 0, zpData: { messages: GEEK_MSGS } };
+            }
+            return {};
+        });
+        const rows = await command.func(page, { uid: 'enc-geek-uid', page: 1, side: 'auto' });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].from).toBe('对方');
+    });
+
+    it('--side geek throws when uid is not found in geek chat list', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('document.cookie')) return 'test-enc-sys-id';
+            if (script.includes('geekFilterByLabel')) {
+                return { code: 0, zpData: { friendList: [] } };
+            }
+            return {};
+        });
+        await expect(
+            command.func(page, { uid: 'unknown-uid', page: 1, side: 'geek' })
+        ).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('--side boss maps expired cookies to AuthRequiredError', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('getBossFriendListV2')) {
+                return { code: 7, message: 'Cookie 已过期' };
+            }
+            return {};
+        });
+        await expect(
+            command.func(page, { uid: 'enc-boss-uid', page: 1, side: 'boss' })
+        ).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('--side boss treats missing history list as parser drift', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('getBossFriendListV2')) {
+                return { code: 0, zpData: { friendList: [BOSS_FRIEND] } };
+            }
+            if (script.includes('boss/historyMsg')) {
+                return { code: 0, zpData: {} };
+            }
+            return {};
+        });
+        await expect(
+            command.func(page, { uid: 'enc-boss-uid', page: 1, side: 'boss' })
+        ).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('--side geek reports an empty history as EmptyResultError', async () => {
+        const page = createPageMock(async (script) => {
+            if (script.includes('document.cookie')) return 'test-enc-sys-id';
+            if (script.includes('geekFilterByLabel')) {
+                return { code: 0, zpData: { friendList: [GEEK_FRIEND_LABEL] } };
+            }
+            if (script.includes('getGeekFriendList.json')) {
+                return { code: 0, zpData: { result: [GEEK_FRIEND_ENRICHED] } };
+            }
+            if (script.includes('geek/historyMsg')) {
+                return { code: 0, zpData: { messages: [] } };
+            }
+            return {};
+        });
+        await expect(
+            command.func(page, { uid: 'enc-geek-uid', page: 1, side: 'geek' })
+        ).rejects.toBeInstanceOf(EmptyResultError);
+    });
+});

package/clis/boss/utils.js

@@ -1,3 +1,5 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
 // ── Constants ───────────────────────────────────────────────────────────────
 const BOSS_DOMAIN = 'www.zhipin.com';
 const CHAT_URL = `https://${BOSS_DOMAIN}/web/chat/index`;
@@ -10,7 +12,24 @@ const DEFAULT_TIMEOUT = 15_000;
  */
 export function requirePage(page) {
     if (!page)
-        throw new Error('Browser page required');
+        throw new CommandExecutionError('Browser page required');
+}
+export function readPositiveInteger(raw, name, fallback, max) {
+    const value = raw === undefined || raw === null || raw === '' ? fallback : Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new ArgumentError(`boss ${name} must be a positive integer`);
+    }
+    if (max !== undefined && value > max) {
+        throw new ArgumentError(`boss ${name} must be <= ${max}`);
+    }
+    return value;
+}
+export function readRequiredString(raw, name) {
+    const value = String(raw ?? '').trim();
+    if (!value) {
+        throw new ArgumentError(`boss ${name} cannot be empty`);
+    }
+    return value;
 }
 /**
  * Navigate to BOSS chat page and wait for it to settle.
@@ -33,7 +52,7 @@ export async function navigateTo(page, url, waitSeconds = 1) {
  */
 export function checkAuth(data) {
     if (COOKIE_EXPIRED_CODES.has(data.code)) {
-        throw new Error(COOKIE_EXPIRED_MSG);
+        throw new AuthRequiredError(BOSS_DOMAIN, COOKIE_EXPIRED_MSG);
     }
 }
 /**
@@ -41,11 +60,14 @@ export function checkAuth(data) {
  * Checks for cookie expiry first, then throws with the provided message.
  */
 export function assertOk(data, errorPrefix) {
+    if (!data || typeof data !== 'object') {
+        throw new CommandExecutionError(`${errorPrefix ? `${errorPrefix}: ` : ''}Boss API returned malformed response`);
+    }
     if (data.code === 0)
         return;
     checkAuth(data);
     const prefix = errorPrefix ? `${errorPrefix}: ` : '';
-    throw new Error(`${prefix}${data.message || 'Unknown error'} (code=${data.code})`);
+    throw new CommandExecutionError(`${prefix}${data.message || 'Unknown error'} (code=${data.code})`);
 }
 /**
  * Make a credentialed XHR request via page.evaluate().
@@ -80,7 +102,19 @@ export async function bossFetch(page, url, opts = {}) {
       });
     }
   `;
-    const data = await page.evaluate(script);
+    let data;
+    try {
+        data = await page.evaluate(script);
+    } catch (error) {
+        if (error instanceof AuthRequiredError || error instanceof CommandExecutionError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(`Boss API request failed: ${message}`);
+    }
+    if (!data || typeof data !== 'object') {
+        throw new CommandExecutionError('Boss API returned malformed response');
+    }
     // Auto-check auth unless caller opts out
     if (!opts.allowNonZero && data.code !== 0) {
         assertOk(data);
@@ -95,8 +129,13 @@ export async function fetchFriendList(page, opts = {}) {
     const pageNum = opts.pageNum ?? 1;
     const jobId = opts.jobId ?? '0';
     const url = `https://${BOSS_DOMAIN}/wapi/zprelation/friend/getBossFriendListV2.json?page=${pageNum}&status=0&jobId=${jobId}`;
-    const data = await bossFetch(page, url);
-    return data.zpData?.friendList || [];
+    const data = await bossFetch(page, url, { allowNonZero: opts.allowNonZero });
+    if (opts.allowNonZero && data.code !== 0) return data;
+    const list = data.zpData?.friendList;
+    if (!Array.isArray(list)) {
+        throw new CommandExecutionError('Boss friend list response did not include zpData.friendList');
+    }
+    return list;
 }
 /**
  * Fetch the recommended candidates (greetRecSortList).
@@ -104,7 +143,11 @@ export async function fetchFriendList(page, opts = {}) {
 export async function fetchRecommendList(page) {
     const url = `https://${BOSS_DOMAIN}/wapi/zprelation/friend/greetRecSortList`;
     const data = await bossFetch(page, url);
-    return data.zpData?.friendList || [];
+    const list = data.zpData?.friendList;
+    if (!Array.isArray(list)) {
+        throw new CommandExecutionError('Boss recommend response did not include zpData.friendList');
+    }
+    return list;
 }
 /**
  * Find a friend by encryptUid, searching through friend list and optionally greet list.
@@ -115,10 +158,14 @@ export async function findFriendByUid(page, encryptUid, opts = {}) {
     const checkGreetList = opts.checkGreetList ?? false;
     // Search friend list pages
     for (let p = 1; p <= maxPages; p++) {
-        const friends = await fetchFriendList(page, { pageNum: p });
+        const result = await fetchFriendList(page, { pageNum: p, allowNonZero: opts.allowNonZero });
+        if (opts.allowNonZero && !Array.isArray(result)) {
+            return { friend: null, code: result.code };
+        }
+        const friends = Array.isArray(result) ? result : [];
         const found = friends.find((f) => f.encryptUid === encryptUid);
         if (found)
-            return found;
+            return opts.allowNonZero ? { friend: found, code: 0 } : found;
         if (friends.length === 0)
             break;
     }
@@ -127,9 +174,9 @@ export async function findFriendByUid(page, encryptUid, opts = {}) {
         const greetList = await fetchRecommendList(page);
         const found = greetList.find((f) => f.encryptUid === encryptUid);
         if (found)
-            return found;
+            return opts.allowNonZero ? { friend: found, code: 0 } : found;
     }
-    return null;
+    return opts.allowNonZero ? { friend: null, code: 0 } : null;
 }
 // ── UI automation helpers ───────────────────────────────────────────────────
 /**
@@ -221,3 +268,185 @@ export function verbose(msg) {
         console.error(`[opencli:boss] ${msg}`);
     }
 }
+// ── Geek-side helpers ────────────────────────────────────────────────────────
+export const IDENTITY_MISMATCH_CODE = 24;
+const GEEK_CHAT_URL = `https://${BOSS_DOMAIN}/web/geek/chat`;
+/**
+ * Navigate to the job-seeker chat page.
+ * Establishes the cookie + JS-global context needed for geek-side API calls.
+ */
+export async function navigateToGeekChat(page, waitSeconds = 2) {
+    await page.goto(GEEK_CHAT_URL);
+    await page.wait({ time: waitSeconds });
+}
+/**
+ * Read the encryptSystemId value required by the geek-side list API.
+ * Strategy (in order):
+ *   1. Vue app state / Pinia stores / $route.query (Option 1 — runtime source)
+ *   2. performance.getEntriesByType('resource') — parse from geekFilterByLabel URL
+ *      that the page itself already issued (Option 2 — most deterministic)
+ *   3. cookie, inline <script> SSR state, known window globals, localStorage (fallbacks)
+ * Returns empty string if nothing is found; the API may still succeed without it.
+ * Caller must have navigated to the geek chat page first.
+ */
+export async function readEncryptSystemId(page) {
+    const result = await page.evaluate(`
+    (() => {
+      // 1. Vue app state / Pinia / $route.query
+      // The chat component reads encryptSystemId from the app runtime to build
+      // its own geekFilterByLabel request, so the value lives in the Vue tree.
+      try {
+        const appEl = document.querySelector('#app') || document.querySelector('[data-v-app]');
+        const vueApp = appEl && (appEl.__vue_app__ || appEl._vei);
+        if (vueApp) {
+          // 1a. Pinia stores (Vue 3 standard state management on BOSS直聘)
+          const pinia = vueApp.config && vueApp.config.globalProperties.$pinia;
+          if (pinia && pinia.state && pinia.state.value) {
+            for (const store of Object.values(pinia.state.value)) {
+              try {
+                const flat = JSON.stringify(store);
+                if (flat.includes('encryptSystemId')) {
+                  const m = flat.match(/"encryptSystemId":"([^"]+)"/);
+                  if (m) return m[1];
+                }
+              } catch (_) {}
+            }
+          }
+          // 1b. Vue Router current route query
+          const router = vueApp.config && vueApp.config.globalProperties.$router;
+          const query = router && router.currentRoute && router.currentRoute.value && router.currentRoute.value.query;
+          if (query && query.encryptSystemId) return query.encryptSystemId;
+        }
+      } catch (_) {}
+      // 2. Performance resource entries — the page already issued geekFilterByLabel
+      // with encryptSystemId in the URL; read it back from the resource timing API.
+      try {
+        const entries = performance.getEntriesByType('resource');
+        for (const entry of entries) {
+          if (!entry.name.includes('geekFilterByLabel')) continue;
+          const u = new URL(entry.name);
+          const v = u.searchParams.get('encryptSystemId');
+          if (v) return v;
+        }
+      } catch (_) {}
+      // 3. cookie
+      try {
+        const m = document.cookie.match(/encryptSystemId=([^;]+)/i);
+        if (m) return decodeURIComponent(m[1]);
+      } catch (_) {}
+      // 4. inline <script> SSR state (Nuxt embeds server state here)
+      try {
+        for (const s of document.querySelectorAll('script:not([src])')) {
+          const t = s.textContent || '';
+          if (!t.includes('encryptSystemId')) continue;
+          const m = t.match(/"encryptSystemId":"([^"]+)"/);
+          if (m) return m[1];
+        }
+      } catch (_) {}
+      // 5. known BOSS / Nuxt window globals
+      const KNOWN = [
+        '__NUXT__', '__INITIAL_STATE__', '__ZP_INFO__', '__BOSS_ZP__',
+        'pageGlobalVar', 'ZP_DATA', '__ZP_DATA__', '__PAGE_DATA__',
+      ];
+      for (const k of KNOWN) {
+        const obj = window[k];
+        if (!obj || typeof obj !== 'object') continue;
+        try {
+          const flat = JSON.stringify(obj);
+          if (!flat.includes('encryptSystemId')) continue;
+          const m = flat.match(/"encryptSystemId":"([^"]+)"/);
+          if (m) return m[1];
+        } catch (_) {}
+      }
+      // 6. localStorage
+      try {
+        for (let i = 0; i < localStorage.length; i++) {
+          const k = localStorage.key(i);
+          if (!k) continue;
+          if (k.toLowerCase().includes('encryptsystemid')) {
+            const v = localStorage.getItem(k);
+            if (v) return v;
+          }
+          const v = localStorage.getItem(k) || '';
+          if (v.includes('encryptSystemId')) {
+            const m = v.match(/"encryptSystemId":"([^"]+)"/);
+            if (m) return m[1];
+          }
+        }
+      } catch (_) {}
+      return '';
+    })()
+  `);
+    return result || '';
+}
+/**
+ * Fetch the job-seeker chat list (brief info, no securityId).
+ * Use fetchGeekFriendInfoList to enrich with securityId before calling chatmsg.
+ */
+export async function fetchGeekFriendLabelList(page, opts = {}) {
+    const labelId = opts.labelId ?? 0;
+    const encryptSystemId = opts.encryptSystemId ?? '';
+    const url = `https://${BOSS_DOMAIN}/wapi/zprelation/friend/geekFilterByLabel?labelId=${labelId}&encryptSystemId=${encodeURIComponent(encryptSystemId)}`;
+    const data = await bossFetch(page, url, { allowNonZero: opts.allowNonZero });
+    if (opts.allowNonZero && data.code !== 0) return data;
+    const list = data.zpData?.friendList;
+    if (!Array.isArray(list)) {
+        throw new CommandExecutionError('Boss geek chat list response did not include zpData.friendList');
+    }
+    return list;
+}
+/**
+ * Enrich a batch of geek friends with full fields including securityId.
+ * Processes in batches of 50 to avoid oversized request bodies.
+ */
+export async function fetchGeekFriendInfoList(page, friendIds = []) {
+    if (!friendIds.length) return [];
+    const BATCH_SIZE = 50;
+    const results = [];
+    for (let i = 0; i < friendIds.length; i += BATCH_SIZE) {
+        const batch = friendIds.slice(i, i + BATCH_SIZE).map(String);
+        const body = `friendIds=${batch.join(',')}`;
+        const data = await bossFetch(page, `https://${BOSS_DOMAIN}/wapi/zprelation/friend/getGeekFriendList.json`, {
+            method: 'POST',
+            body,
+        });
+        const batchResult = data.zpData?.result;
+        if (!Array.isArray(batchResult)) {
+            throw new CommandExecutionError('Boss geek friend enrichment response did not include zpData.result');
+        }
+        results.push(...batchResult);
+    }
+    return results;
+}
+/**
+ * Find a geek-side friend by encrypted uid.
+ * Merges label-list and enriched data; returns null if not found.
+ */
+export async function findGeekFriendByUid(page, encryptUid, opts = {}) {
+    const labelList = await fetchGeekFriendLabelList(page, { encryptSystemId: opts.encryptSystemId });
+    const candidate = labelList.find((f) => f.encryptFriendId === encryptUid ||
+        String(f.uid) === String(encryptUid) ||
+        String(f.friendId) === String(encryptUid));
+    if (!candidate) return null;
+    const enriched = await fetchGeekFriendInfoList(page, [candidate.friendId]);
+    return { ...candidate, ...(enriched[0] || {}) };
+}
+/**
+ * Fetch message history for a geek-side chat.
+ * friend must have .uid (boss's numeric id) and .securityId.
+ */
+export async function fetchGeekHistoryMsg(page, friend, opts = {}) {
+    const pageNum = opts.page ?? 1;
+    const bossId = friend.uid;
+    const securityId = encodeURIComponent(friend.securityId || '');
+    const url = `https://${BOSS_DOMAIN}/wapi/zpchat/geek/historyMsg?bossId=${bossId}&securityId=${securityId}&page=${pageNum}&c=20&src=0`;
+    const data = await bossFetch(page, url);
+    const messages = data.zpData?.messages ?? data.zpData?.historyMsgList;
+    if (!Array.isArray(messages)) {
+        throw new CommandExecutionError('Boss geek history response did not include a message list');
+    }
+    if (messages.length === 0) {
+        throw new EmptyResultError('boss chatmsg', 'Boss returned no messages for this chat.');
+    }
+    return messages;
+}

package/clis/brave/search.js

@@ -0,0 +1,80 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+  emptySearchResults,
+  requireBoundedInteger,
+  requireNonNegativeInteger,
+  requireRows,
+  requireSearchQuery,
+  runBrowserStep,
+  toHttpsUrl,
+} from '../_shared/search-adapter.js';
+
+function buildExtractorJs(limit) {
+  return `
+(function() {
+  var results = [];
+  var seen = {};
+  var items = document.querySelectorAll('.snippet');
+  for (var i = 0; i < items.length; i++) {
+    if (results.length >= ${limit}) break;
+    var el = items[i];
+    if (el.classList.contains('standalone') || el.classList.contains('ad')) continue;
+    var titleEl = el.querySelector('.search-snippet-title');
+    var snippetEl = el.querySelector('.generic-snippet .content');
+    var linkEl = el.querySelector('.result-content a');
+    if (!titleEl) continue;
+    var title = titleEl.textContent.trim();
+    var href = linkEl ? linkEl.getAttribute('href') || '' : '';
+    var snippet = snippetEl ? snippetEl.textContent.trim() : '';
+    if (!title || !href || seen[href]) continue;
+    if (href.indexOf('/') === 0) continue;
+    seen[href] = true;
+    results.push([title, href, snippet]);
+  }
+  return results;
+})()`;
+}
+
+const command = cli({
+  site: 'brave',
+  name: 'search',
+  access: 'read',
+  description: 'Search Brave Search',
+  domain: 'search.brave.com',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  args: [
+    { name: 'keyword', positional: true, required: true, help: 'Search query' },
+    { name: 'limit', type: 'int', default: 10, help: 'Number of results per page (max 18)' },
+    { name: 'offset', type: 'int', default: 0, help: 'Page offset (0, 1, 2...). Brave returns ~18 results per page' },
+  ],
+  columns: ['rank', 'title', 'url', 'snippet'],
+  func: async (page, kwargs) => {
+    const limit = requireBoundedInteger(kwargs.limit, 10, 1, 18, '--limit');
+    const query = requireSearchQuery(kwargs.keyword);
+    const keyword = encodeURIComponent(query);
+    const offset = requireNonNegativeInteger(kwargs.offset, 0, '--offset');
+    let url = `https://search.brave.com/search?q=${keyword}`;
+    if (offset > 0) url += `&offset=${offset}`;
+    await runBrowserStep('brave search navigation', () => page.goto(url));
+    try {
+      await page.wait({ selector: '.snippet', timeout: 10 });
+    } catch {
+      await page.wait(3).catch(function() {});
+    }
+    const raw = await runBrowserStep('brave search extraction', () => page.evaluate(buildExtractorJs(limit)));
+    const results = requireRows(raw, 'brave search');
+    if (results.length === 0) {
+      throw emptySearchResults('Brave', query);
+    }
+    const rows = results
+      .map(function(r, index) {
+        return { rank: index + 1 + offset * 18, title: r[0], url: toHttpsUrl(r[1], 'https://search.brave.com'), snippet: r[2] };
+      })
+      .filter((row) => row.url);
+    if (rows.length === 0) throw emptySearchResults('Brave', query);
+    return rows;
+  },
+});
+
+export const __test__ = { command };