@jackwener/opencli 1.3.2 → 1.4.0

package/src/clis/cursor/dump.ts

@@ -1,28 +1,3 @@
-import { cli, Strategy } from '../../registry.js';
-import * as fs from 'fs';
+import { makeDumpCommand } from '../_shared/desktop-commands.js';
 
-export const dumpCommand = cli({
-  site: 'cursor',
-  name: 'dump',
-  description: 'Dump the DOM and Accessibility tree of Cursor for reverse-engineering',
-  domain: 'localhost',
-  strategy: Strategy.UI,
-  browser: true,
-  columns: ['action', 'files'],
-  func: async (page) => {
-    // Extract full HTML
-    const dom = await page.evaluate('document.body.innerHTML');
-    fs.writeFileSync('/tmp/cursor-dom.html', dom);
-
-    // Get accessibility snapshot
-    const snap = await page.snapshot({ interactive: false });
-    fs.writeFileSync('/tmp/cursor-snapshot.json', JSON.stringify(snap, null, 2));
-
-    return [
-      {
-        action: 'Dom extraction finished',
-        files: '/tmp/cursor-dom.html, /tmp/cursor-snapshot.json',
-      },
-    ];
-  },
-});
+export const dumpCommand = makeDumpCommand('cursor');

package/src/clis/cursor/new.ts

@@ -1,21 +1,3 @@
-import { cli, Strategy } from '../../registry.js';
-import type { IPage } from '../../types.js';
+import { makeNewCommand } from '../_shared/desktop-commands.js';
 
-export const newCommand = cli({
-  site: 'cursor',
-  name: 'new',
-  description: 'Start a new Cursor chat or Composer session',
-  domain: 'localhost',
-  strategy: Strategy.UI,
-  browser: true,
-  args: [],
-  columns: ['Status'],
-  func: async (page: IPage) => {
-    // Use keyboard shortcut — most robust approach, avoids brittle DOM selectors
-    const isMac = process.platform === 'darwin';
-    await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
-    await page.wait(1);
-
-    return [{ Status: 'Success' }];
-  },
-});
+export const newCommand = makeNewCommand('cursor', 'Cursor chat or Composer');

package/src/clis/cursor/read.ts

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { EmptyResultError } from '../../errors.js';
 import type { IPage } from '../../types.js';
 
 export const readCommand = cli({
@@ -39,7 +40,7 @@ export const readCommand = cli({
     `);
 
     if (!history || history.length === 0) {
-      throw new Error('No conversation history found in Cursor.');
+      throw new EmptyResultError('cursor read', 'No conversation history found in Cursor.');
     }
 
     return history;

package/src/clis/cursor/screenshot.ts

@@ -1,38 +1,3 @@
-import * as fs from 'node:fs';
-import { cli, Strategy } from '../../registry.js';
-import type { IPage } from '../../types.js';
-
-function makeScreenshotCommand(site: string) {
-  return cli({
-    site,
-    name: 'screenshot',
-    description: `Capture a snapshot of the current ${site} window (DOM + Accessibility tree)`,
-    domain: 'localhost',
-    strategy: Strategy.UI,
-    browser: true,
-    args: [
-      { name: 'output', required: false,  help: `Output file path (default: /tmp/${site}-snapshot.txt)` },
-    ],
-    columns: ['Status', 'File'],
-    func: async (page: IPage, kwargs: any) => {
-      const outputPath = (kwargs.output as string) || `/tmp/${site}-snapshot.txt`;
-
-      // Get both the accessibility snapshot and the raw DOM HTML
-      const snap = await page.snapshot({ compact: true });
-      const html = await page.evaluate('document.documentElement.outerHTML');
-
-      const htmlPath = outputPath.replace(/\.\w+$/, '') + '-dom.html';
-      const snapPath = outputPath.replace(/\.\w+$/, '') + '-a11y.txt';
-
-      fs.writeFileSync(htmlPath, html);
-      fs.writeFileSync(snapPath, typeof snap === 'string' ? snap : JSON.stringify(snap, null, 2));
-
-      return [
-        { Status: 'Success', File: htmlPath },
-        { Status: 'Success', File: snapPath },
-      ];
-    },
-  });
-}
+import { makeScreenshotCommand } from '../_shared/desktop-commands.js';
 
 export const screenshotCursor = makeScreenshotCommand('cursor');

package/src/clis/cursor/send.ts

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { SelectorError } from '../../errors.js';
 import type { IPage } from '../../types.js';
 
 export const sendCommand = cli({
@@ -29,7 +30,7 @@ export const sendCommand = cli({
     );
 
     if (!injected) {
-      throw new Error('Could not find Cursor Composer input element.');
+      throw new SelectorError('Cursor Composer input element');
     }
 
     // Submit the command. In Cursor, Enter usually submits the chat.

package/src/clis/cursor/status.ts

@@ -1,23 +1,3 @@
-import { cli, Strategy } from '../../registry.js';
+import { makeStatusCommand } from '../_shared/desktop-commands.js';
 
-export const statusCommand = cli({
-  site: 'cursor',
-  name: 'status',
-  description: 'Check active CDP connection to Cursor AI Editor',
-  domain: 'localhost',
-  strategy: Strategy.UI, // Interactive UI manipulation
-  browser: true,
-  columns: ['Status', 'Url', 'Title'],
-  func: async (page) => {
-    const url = await page.evaluate('window.location.href');
-    const title = await page.evaluate('document.title');
-
-    return [
-      {
-        Status: 'Connected',
-        Url: url,
-        Title: title,
-      },
-    ];
-  },
-});
+export const statusCommand = makeStatusCommand('cursor', 'Cursor AI Editor');

package/src/clis/dictionary/examples.yaml

@@ -0,0 +1,25 @@
+site: dictionary
+name: examples
+description: Read real-world example sentences utilizing the word
+domain: api.dictionaryapi.dev
+strategy: public
+browser: false
+
+args:
+  word:
+    type: string
+    required: true
+    positional: true
+    description: Word to get example sentences for
+
+pipeline:
+  - fetch:
+      url: "https://api.dictionaryapi.dev/api/v2/entries/en/${{ args.word | urlencode }}"
+
+  - map:
+      word: "${{ item.word }}"
+      example: "${{ (() => { if (item.meanings) { for (const m of item.meanings) { if (m.definitions) { for (const d of m.definitions) { if (d.example) return d.example; } } } } return 'No example found in API.'; })() }}"
+
+  - limit: 1
+
+columns: [word, example]

package/src/clis/dictionary/search.yaml

@@ -0,0 +1,27 @@
+site: dictionary
+name: search
+description: Search the Free Dictionary API for definitions, parts of speech, and pronunciations.
+domain: api.dictionaryapi.dev
+strategy: public
+browser: false
+
+args:
+  word:
+    type: string
+    required: true
+    positional: true
+    description: Word to define (e.g., serendipity)
+
+pipeline:
+  - fetch:
+      url: "https://api.dictionaryapi.dev/api/v2/entries/en/${{ args.word | urlencode }}"
+
+  - map:
+      word: "${{ item.word }}"
+      phonetic: "${{ (() => { if (item.phonetic) return item.phonetic; if (item.phonetics) { for (const p of item.phonetics) { if (p.text) return p.text; } } return ''; })() }}"
+      type: "${{ (() => { if (item.meanings && item.meanings[0] && item.meanings[0].partOfSpeech) return item.meanings[0].partOfSpeech; return 'N/A'; })() }}"
+      definition: "${{ (() => { if (item.meanings && item.meanings[0] && item.meanings[0].definitions && item.meanings[0].definitions[0] && item.meanings[0].definitions[0].definition) return item.meanings[0].definitions[0].definition; return 'No definition found in API.'; })() }}"
+
+  - limit: 1
+
+columns: [word, phonetic, type, definition]

package/src/clis/dictionary/synonyms.yaml

@@ -0,0 +1,25 @@
+site: dictionary
+name: synonyms
+description: Find synonyms for a specific word
+domain: api.dictionaryapi.dev
+strategy: public
+browser: false
+
+args:
+  word:
+    type: string
+    required: true
+    positional: true
+    description: Word to find synonyms for (e.g., serendipity)
+
+pipeline:
+  - fetch:
+      url: "https://api.dictionaryapi.dev/api/v2/entries/en/${{ args.word | urlencode }}"
+
+  - map:
+      word: "${{ item.word }}"
+      synonyms: "${{ (() => { const s = new Set(); if (item.meanings) { for (const m of item.meanings) { if (m.synonyms) { for (const syn of m.synonyms) s.add(syn); } if (m.definitions) { for (const d of m.definitions) { if (d.synonyms) { for (const syn of d.synonyms) s.add(syn); } } } } } const arr = Array.from(s); return arr.length > 0 ? arr.slice(0, 5).join(', ') : 'No synonyms found in API.'; })() }}"
+
+  - limit: 1
+
+columns: [word, synonyms]

package/src/clis/douban/book-hot.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { loadDoubanBookHot } from './shared.js';
+import { loadDoubanBookHot } from './utils.js';
 
 cli({
   site: 'douban',

package/src/clis/douban/movie-hot.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { loadDoubanMovieHot } from './shared.js';
+import { loadDoubanMovieHot } from './utils.js';
 
 cli({
   site: 'douban',

package/src/clis/douban/search.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { searchDouban } from './shared.js';
+import { searchDouban } from './utils.js';
 
 cli({
   site: 'douban',

package/src/clis/douban/utils.ts

@@ -1,9 +1,173 @@
 /**
- * Douban movie adapter utilities.
+ * Douban adapter utilities.
  */
 
+import { CliError } from '../../errors.js';
 import type { IPage } from '../../types.js';
 
+function clampLimit(limit: number): number {
+  return Math.max(1, Math.min(limit || 20, 50));
+}
+
+async function ensureDoubanReady(page: IPage): Promise<void> {
+  const state = await page.evaluate(`
+    (() => {
+      const title = (document.title || '').trim();
+      const href = (location.href || '').trim();
+      const blocked = href.includes('sec.douban.com') || /登录跳转/.test(title) || /异常请求/.test(document.body?.innerText || '');
+      return { blocked, title, href };
+    })()
+  `);
+  if (state?.blocked) {
+    throw new CliError(
+      'AUTH_REQUIRED',
+      'Douban requires a logged-in browser session before these commands can load data.',
+      'Please sign in to douban.com in the browser that opencli reuses, then rerun the command.',
+    );
+  }
+}
+
+export async function loadDoubanBookHot(page: IPage, limit: number): Promise<any[]> {
+  const safeLimit = clampLimit(limit);
+  await page.goto('https://book.douban.com/chart');
+  await page.wait(4);
+  await ensureDoubanReady(page);
+  const data = await page.evaluate(`
+    (() => {
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const books = [];
+      for (const el of Array.from(document.querySelectorAll('.media.clearfix'))) {
+        try {
+          const titleEl = el.querySelector('h2 a[href*="/subject/"]');
+          const title = normalize(titleEl?.textContent);
+          let url = titleEl?.getAttribute('href') || '';
+          if (!title || !url) continue;
+          if (!url.startsWith('http')) url = 'https://book.douban.com' + url;
+
+          const info = normalize(el.querySelector('.subject-abstract, .pl, .pub')?.textContent);
+          const infoParts = info.split('/').map((part) => part.trim()).filter(Boolean);
+          const ratingText = normalize(el.querySelector('.subject-rating .font-small, .rating_nums, .rating')?.textContent);
+          const quote = Array.from(el.querySelectorAll('.subject-tags .tag'))
+            .map((node) => normalize(node.textContent))
+            .filter(Boolean)
+            .join(' / ');
+
+          books.push({
+            rank: parseInt(normalize(el.querySelector('.green-num-box')?.textContent), 10) || books.length + 1,
+            title,
+            rating: parseFloat(ratingText) || 0,
+            quote,
+            author: infoParts[0] || '',
+            publisher: infoParts.find((part) => /出版社|出版公司|Press/i.test(part)) || infoParts[2] || '',
+            year: infoParts.find((part) => /\\d{4}(?:-\\d{1,2})?/.test(part))?.match(/\\d{4}/)?.[0] || '',
+            price: infoParts.find((part) => /元|USD|\\$|￥/.test(part)) || '',
+            url,
+            cover: el.querySelector('img')?.getAttribute('src') || '',
+          });
+        } catch {}
+      }
+      return books.slice(0, ${safeLimit});
+    })()
+  `);
+  return Array.isArray(data) ? data : [];
+}
+
+export async function loadDoubanMovieHot(page: IPage, limit: number): Promise<any[]> {
+  const safeLimit = clampLimit(limit);
+  await page.goto('https://movie.douban.com/chart');
+  await page.wait(4);
+  await ensureDoubanReady(page);
+  const data = await page.evaluate(`
+    (() => {
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const results = [];
+      for (const el of Array.from(document.querySelectorAll('.item'))) {
+        const titleEl = el.querySelector('.pl2 a');
+        const title = normalize(titleEl?.textContent);
+        let url = titleEl?.getAttribute('href') || '';
+        if (!title || !url) continue;
+        if (!url.startsWith('http')) url = 'https://movie.douban.com' + url;
+
+        const info = normalize(el.querySelector('.pl2 p')?.textContent);
+        const infoParts = info.split('/').map((part) => part.trim()).filter(Boolean);
+        const releaseIndex = (() => {
+          for (let i = infoParts.length - 1; i >= 0; i -= 1) {
+            if (/\\d{4}-\\d{2}-\\d{2}|\\d{4}\\/\\d{2}\\/\\d{2}/.test(infoParts[i])) return i;
+          }
+          return -1;
+        })();
+        const directorPart = releaseIndex >= 1 ? infoParts[releaseIndex - 1] : '';
+        const regionPart = releaseIndex >= 2 ? infoParts[releaseIndex - 2] : '';
+        const yearMatch = info.match(/\\b(19|20)\\d{2}\\b/);
+        results.push({
+          rank: results.length + 1,
+          title,
+          rating: parseFloat(normalize(el.querySelector('.rating_nums')?.textContent)) || 0,
+          quote: normalize(el.querySelector('.inq')?.textContent),
+          director: directorPart.replace(/^导演:\\s*/, ''),
+          year: yearMatch?.[0] || '',
+          region: regionPart,
+          url,
+          cover: el.querySelector('img')?.getAttribute('src') || '',
+        });
+        if (results.length >= ${safeLimit}) break;
+      }
+      return results;
+    })()
+  `);
+  return Array.isArray(data) ? data : [];
+}
+
+export async function searchDouban(page: IPage, type: string, keyword: string, limit: number): Promise<any[]> {
+  const safeLimit = clampLimit(limit);
+  await page.goto(`https://search.douban.com/${encodeURIComponent(type)}/subject_search?search_text=${encodeURIComponent(keyword)}`);
+  await page.wait(2);
+  await ensureDoubanReady(page);
+  const data = await page.evaluate(`
+    (async () => {
+      const type = ${JSON.stringify(type)};
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const seen = new Set();
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+      for (let i = 0; i < 20; i += 1) {
+        if (document.querySelector('.item-root .title-text, .item-root .title a')) break;
+        await sleep(300);
+      }
+
+      const items = Array.from(document.querySelectorAll('.item-root'));
+
+      const results = [];
+      for (const el of items) {
+        const titleEl = el.querySelector('.title-text, .title a, a[title]');
+        const title = normalize(titleEl?.textContent) || normalize(titleEl?.getAttribute('title'));
+        let url = titleEl?.getAttribute('href') || '';
+        if (!title || !url) continue;
+        if (!url.startsWith('http')) url = 'https://search.douban.com' + url;
+        if (!url.includes('/subject/') || seen.has(url)) continue;
+        seen.add(url);
+        const ratingText = normalize(el.querySelector('.rating_nums')?.textContent);
+        const abstract = normalize(
+          el.querySelector('.meta.abstract, .meta, .abstract, p')?.textContent,
+        );
+        results.push({
+          rank: results.length + 1,
+          id: url.match(/subject\\/(\\d+)/)?.[1] || '',
+          type,
+          title,
+          rating: ratingText.includes('.') ? parseFloat(ratingText) : 0,
+          abstract: abstract.slice(0, 100) + (abstract.length > 100 ? '...' : ''),
+          url,
+          cover: el.querySelector('img')?.getAttribute('src') || '',
+        });
+        if (results.length >= ${safeLimit}) break;
+      }
+      return results;
+    })()
+  `);
+  return Array.isArray(data) ? data : [];
+}
+
 /**
  * Get current user's Douban ID from movie.douban.com/mine page
  */

package/src/clis/doubao/ask.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, getDoubaoTranscriptLines, getDoubaoVisibleTurns, sendDoubaoMessage, waitForDoubaoResponse } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoTranscriptLines, getDoubaoVisibleTurns, sendDoubaoMessage, waitForDoubaoResponse } from './utils.js';
 
 export const askCommand = cli({
   site: 'doubao',

package/src/clis/doubao/new.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, startNewDoubaoChat } from './common.js';
+import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, startNewDoubaoChat } from './utils.js';
 
 export const newCommand = cli({
   site: 'doubao',

package/src/clis/doubao/read.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, getDoubaoVisibleTurns } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoVisibleTurns } from './utils.js';
 
 export const readCommand = cli({
   site: 'doubao',

package/src/clis/doubao/send.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, sendDoubaoMessage } from './common.js';
+import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, sendDoubaoMessage } from './utils.js';
 
 export const sendCommand = cli({
   site: 'doubao',

package/src/clis/doubao/status.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, getDoubaoPageState } from './common.js';
+import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, getDoubaoPageState } from './utils.js';
 
 export const statusCommand = cli({
   site: 'doubao',

package/src/clis/doubao-app/ask.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { SEL, injectTextScript, clickSendScript, pollResponseScript } from './common.js';
+import { SEL, injectTextScript, clickSendScript, pollResponseScript } from './utils.js';
 
 export const askCommand = cli({
   site: 'doubao-app',

package/src/clis/doubao-app/new.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { clickNewChatScript } from './common.js';
+import { clickNewChatScript } from './utils.js';
 
 export const newCommand = cli({
   site: 'doubao-app',

package/src/clis/doubao-app/read.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { readMessagesScript } from './common.js';
+import { readMessagesScript } from './utils.js';
 
 export const readCommand = cli({
   site: 'doubao-app',

package/src/clis/doubao-app/send.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { injectTextScript, clickSendScript } from './common.js';
+import { injectTextScript, clickSendScript } from './utils.js';
 
 export const sendCommand = cli({
   site: 'doubao-app',

package/src/clis/grok/ask.test.ts

@@ -1,7 +1,32 @@
 import { describe, expect, it } from 'vitest';
+import type { IPage } from '../../types.js';
 import { __test__ } from './ask.js';
 
 describe('grok ask helpers', () => {
+  describe('isOnGrok', () => {
+    const fakePage = (url: string | Error): IPage =>
+      ({ evaluate: () => url instanceof Error ? Promise.reject(url) : Promise.resolve(url) }) as unknown as IPage;
+
+    it('returns true for grok.com URLs', async () => {
+      expect(await __test__.isOnGrok(fakePage('https://grok.com/'))).toBe(true);
+      expect(await __test__.isOnGrok(fakePage('https://grok.com/chat/abc123'))).toBe(true);
+    });
+
+    it('returns true for grok.com subdomains', async () => {
+      expect(await __test__.isOnGrok(fakePage('https://api.grok.com/v1'))).toBe(true);
+    });
+
+    it('returns false for non-grok domains', async () => {
+      expect(await __test__.isOnGrok(fakePage('https://fakegrok.com/'))).toBe(false);
+      expect(await __test__.isOnGrok(fakePage('https://example.com/?next=grok.com'))).toBe(false);
+      expect(await __test__.isOnGrok(fakePage('about:blank'))).toBe(false);
+    });
+
+    it('returns false when evaluate throws (detached tab)', async () => {
+      expect(await __test__.isOnGrok(fakePage(new Error('detached')))).toBe(false);
+    });
+  });
+
   it('normalizes boolean flags for explicit web routing', () => {
     expect(__test__.normalizeBooleanFlag(true)).toBe(true);
     expect(__test__.normalizeBooleanFlag('true')).toBe(true);

package/src/clis/grok/ask.ts

@@ -53,6 +53,19 @@ function updateStableState(previousText: string, stableCount: number, nextText:
   return { previousText: nextText, stableCount: 0 };
 }
 
+/** Check whether the tab is already on grok.com (any path). */
+async function isOnGrok(page: IPage): Promise<boolean> {
+  // catch handles blank tabs (about:blank) or detached pages
+  const url = await page.evaluate('window.location.href').catch(() => '');
+  if (typeof url !== 'string' || !url) return false;
+  try {
+    const hostname = new URL(url).hostname;
+    return hostname === 'grok.com' || hostname.endsWith('.grok.com');
+  } catch {
+    return false;
+  }
+}
+
 async function runDefaultAsk(
   page: IPage,
   prompt: string,
@@ -60,21 +73,17 @@ async function runDefaultAsk(
   newChat: boolean,
 ) {
   if (newChat) {
+    // Explicitly start a fresh conversation via the homepage
     await page.goto(GROK_URL);
     await page.wait(2);
-    await page.evaluate(`(() => {
-      const btn = [...document.querySelectorAll('a, button')].find(b => {
-        const t = (b.textContent || '').trim().toLowerCase();
-        return t.includes('new') || b.getAttribute('href') === '/';
-      });
-      if (btn) btn.click();
-    })()`);
+    await tryStartFreshChat(page);
     await page.wait(2);
+  } else if (!(await isOnGrok(page))) {
+    // First invocation or tab was recycled — navigate to Grok
+    await page.goto(GROK_URL);
+    await page.wait(3);
   }
 
-  await page.goto(GROK_URL);
-  await page.wait(3);
-
   const promptJson = JSON.stringify(prompt);
   const sendResult = await page.evaluate(`(async () => {
     try {
@@ -249,11 +258,14 @@ async function runExplicitWebAsk(
   timeoutMs: number,
   newChat: boolean,
 ) {
-  await page.goto(GROK_URL, { settleMs: 2000 });
-
   if (newChat) {
+    // Navigate to homepage and start a fresh conversation
+    await page.goto(GROK_URL, { settleMs: 2000 });
     await tryStartFreshChat(page);
     await page.wait(2);
+  } else if (!(await isOnGrok(page))) {
+    // First invocation or tab was recycled — navigate to Grok
+    await page.goto(GROK_URL, { settleMs: 2000 });
   }
 
   const baselineBubbles = await getBubbleTexts(page);
@@ -318,4 +330,5 @@ export const __test__ = {
   updateStableState,
   normalizeBooleanFlag,
   normalizeBubbleText,
+  isOnGrok,
 };

package/src/clis/jd/item.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '../../registry.js';
+import './item.js';
+
+describe('jd item adapter', () => {
+  const command = getRegistry().get('jd/item');
+
+  it('registers the command with correct shape', () => {
+    expect(command).toBeDefined();
+    expect(command!.site).toBe('jd');
+    expect(command!.name).toBe('item');
+    expect(command!.domain).toBe('item.jd.com');
+    expect(command!.strategy).toBe('cookie');
+    expect(typeof command!.func).toBe('function');
+  });
+
+  it('has sku as a required positional arg', () => {
+    const skuArg = command!.args.find((a) => a.name === 'sku');
+    expect(skuArg).toBeDefined();
+    expect(skuArg!.required).toBe(true);
+    expect(skuArg!.positional).toBe(true);
+  });
+
+  it('has images arg with default 10', () => {
+    const imagesArg = command!.args.find((a) => a.name === 'images');
+    expect(imagesArg).toBeDefined();
+    expect(imagesArg!.default).toBe(10);
+  });
+
+  it('includes expected columns', () => {
+    expect(command!.columns).toEqual(
+      expect.arrayContaining(['title', 'price', 'shop', 'specs', 'mainImages', 'detailImages']),
+    );
+  });
+});