@jackwener/opencli 1.7.19 → 1.7.21

package/clis/brave/search.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from 'vitest';
+
+const { __test__ } = await import('./search.js');
+const command = __test__.command;
+
+function createPageMock(evaluateResult = []) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+  };
+}
+
+describe('brave search', () => {
+  it('should register as a valid command', () => {
+    expect(command).toBeDefined();
+    expect(command.site).toBe('brave');
+    expect(command.name).toBe('search');
+    expect(command.access).toBe('read');
+    expect(command.browser).toBe(true);
+    expect(command.strategy).toBe('public');
+    expect(command.domain).toBe('search.brave.com');
+  });
+
+  it('should define keyword positional arg', () => {
+    const kwArg = command.args.find(a => a.name === 'keyword');
+    expect(kwArg).toBeDefined();
+    expect(kwArg.positional).toBe(true);
+    expect(kwArg.required).toBe(true);
+  });
+
+  it('should define limit arg with default 10', () => {
+    const limitArg = command.args.find(a => a.name === 'limit');
+    expect(limitArg).toBeDefined();
+    expect(limitArg.type).toBe('int');
+    expect(limitArg.default).toBe(10);
+  });
+
+  it('should define output columns', () => {
+    expect(command.columns).toContain('rank');
+    expect(command.columns).toContain('title');
+    expect(command.columns).toContain('url');
+    expect(command.columns).toContain('snippet');
+  });
+
+  it('rejects empty query, invalid limit, and invalid offset before navigation', async () => {
+    const page = createPageMock();
+    await expect(command.func(page, { keyword: '', limit: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func(page, { keyword: 'opencli', limit: 19 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func(page, { keyword: 'opencli', limit: 5, offset: -1 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('unwraps browser envelopes and returns ranked HTTPS rows', async () => {
+    const page = createPageMock({
+      session: 'site:brave',
+      data: [['OpenCLI', 'https://github.com/jackwener/OpenCLI', 'CLI browser tooling']],
+    });
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1, offset: 1 })).resolves.toEqual([{
+      rank: 19,
+      title: 'OpenCLI',
+      url: 'https://github.com/jackwener/OpenCLI',
+      snippet: 'CLI browser tooling',
+    }]);
+  });
+
+  it('fails typed instead of silently returning [] for malformed extraction payloads', async () => {
+    const page = createPageMock({ rows: [] });
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1 })).rejects.toMatchObject({
+      code: 'COMMAND_EXEC',
+      message: expect.stringContaining('payload shape'),
+    });
+  });
+});

package/clis/duckduckgo/search.js

@@ -0,0 +1,131 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import {
+  emptySearchResults,
+  requireBoundedInteger,
+  requireNonNegativeInteger,
+  requireRows,
+  requireSearchQuery,
+  runBrowserStep,
+  toHttpsUrl,
+} from '../_shared/search-adapter.js';
+
+function decodeDdgUrl(href) {
+  if (!href) return '';
+  try {
+    const url = new URL(href, 'https://duckduckgo.com');
+    const uddg = url.searchParams.get('uddg');
+    return toHttpsUrl(uddg || href, 'https://duckduckgo.com');
+  } catch {
+    return '';
+  }
+}
+
+function buildExtractFn(limit) {
+  return 'function(doc){' +
+    'var r=[];var seen={};var items=doc.querySelectorAll(".result");' +
+    'for(var i=0;i<items.length;i++){' +
+    'if(r.length>=' + limit + ')break;' +
+    'var el=items[i];var te=el.querySelector(".result__a");' +
+    'var se=el.querySelector(".result__snippet");' +
+    'var ue=el.querySelector(".result__url");' +
+    'var ie=el.querySelector(".result__icon__img");' +
+    'var cls=el.className||"";var rt="web";' +
+    'if(cls.indexOf("result--ad")!==-1||cls.indexOf("result--ads")!==-1||cls.indexOf("badge--ad")!==-1)continue;' +
+    'if(!te)continue;' +
+    'var t=(te.textContent||"").trim();' +
+    'var h=te.getAttribute("href")||"";' +
+    'var sn=se?(se.textContent||"").trim():"";' +
+    'var du=ue?(ue.textContent||"").trim():"";' +
+    'var ic=ie?(ie.getAttribute("src")||""):"";' +
+    'if(cls.indexOf("news-result")!==-1)rt="news";' +
+    'else if(cls.indexOf("video-result")!==-1)rt="video";' +
+    'else if(cls.indexOf("image-result")!==-1)rt="image";' +
+    'if(!t||!h||seen[h])continue;seen[h]=true;' +
+    'r.push([t,h,sn,du,ic,rt]);' +
+    '}return r;}';
+}
+
+function buildExtractorJs(limit) {
+  return '(' + buildExtractFn(limit) + '(document))';
+}
+
+function buildPaginateJs(limit, keyword, offset, region) {
+  var params = 'q=' + encodeURIComponent(keyword) + '&s=' + offset + '&v=l&o=json';
+  if (region) params += '&kl=' + encodeURIComponent(region);
+  return (
+    'new Promise(function($r){' +
+    'var x=new XMLHttpRequest();' +
+    'x.open("POST","/html/",true);' +
+    'x.setRequestHeader("Content-Type","application/x-www-form-urlencoded");' +
+    'x.onload=function(){' +
+    'try{var d=new DOMParser().parseFromString(x.responseText,"text/html");' +
+    '$r(' + buildExtractFn(limit) + '(d));' +
+    '}catch(e){$r({error:"parse",message:String(e&&e.message||e)})}' +
+    '};' +
+    'x.onerror=function(){$r({error:"network"})};' +
+    'x.send("' + params + '");' +
+    '})'
+  );
+}
+
+const command = cli({
+  site: 'duckduckgo',
+  name: 'search',
+  access: 'read',
+  description: 'Search DuckDuckGo',
+  domain: 'html.duckduckgo.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 (1-10). For multi-page, use --offset' },
+    { name: 'offset', type: 'int', default: 0, help: 'Result offset for pagination (0, 10, 20...). Uses XHR POST internally' },
+    { name: 'region', help: 'Region code (e.g. jp-jp, us-en, cn-zh). Default: all regions' },
+    { name: 'time', help: 'Time range: d (day), w (week), m (month), y (year)' },
+  ],
+  columns: ['rank', 'title', 'url', 'snippet', 'displayUrl', 'icon', 'resultType'],
+  func: async (page, kwargs) => {
+    const limit = requireBoundedInteger(kwargs.limit, 10, 1, 10, '--limit');
+    const keyword = requireSearchQuery(kwargs.keyword);
+    const offset = requireNonNegativeInteger(kwargs.offset, 0, '--offset');
+    if (offset % 10 !== 0) {
+      throw new ArgumentError('--offset must be a multiple of 10 for DuckDuckGo HTML pagination');
+    }
+    if (kwargs.time && !/^(d|w|m|y)$/.test(String(kwargs.time))) {
+      throw new ArgumentError('--time must be one of d, w, m, or y');
+    }
+    let url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(keyword)}`;
+    if (kwargs.region) url += `&kl=${encodeURIComponent(String(kwargs.region))}`;
+    if (kwargs.time) url += `&df=${encodeURIComponent(String(kwargs.time))}`;
+    await runBrowserStep('duckduckgo search navigation', () => page.goto(url));
+    try {
+      await page.wait({ selector: '.result', timeout: 8 });
+    } catch {
+      await page.wait(3).catch(function() {});
+    }
+    var raw;
+    if (offset === 0) {
+      raw = await runBrowserStep('duckduckgo search extraction', () => page.evaluate(buildExtractorJs(limit)));
+    } else {
+      raw = await runBrowserStep('duckduckgo search pagination extraction', () => page.evaluate(buildPaginateJs(limit, keyword, offset, kwargs.region)));
+    }
+    const rows = requireRows(raw, 'duckduckgo search');
+    if (rows.length === 0) {
+      throw emptySearchResults('DuckDuckGo', keyword);
+    }
+    return rows.map(function(r, index) {
+      return {
+        rank: index + 1 + offset,
+        title: r[0],
+        url: decodeDdgUrl(r[1]),
+        snippet: r[2],
+        displayUrl: r[3],
+        icon: r[4],
+        resultType: r[5],
+      };
+    }).filter((row) => row.url);
+  },
+});
+
+export const __test__ = { command };

package/clis/duckduckgo/search.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi } from 'vitest';
+import { JSDOM } from 'jsdom';
+
+const { __test__ } = await import('./search.js');
+const command = __test__.command;
+
+function createPageMock(evaluateResult = []) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+  };
+}
+
+describe('duckduckgo search', () => {
+  it('should register as a valid command', () => {
+    expect(command).toBeDefined();
+    expect(command.site).toBe('duckduckgo');
+    expect(command.name).toBe('search');
+    expect(command.access).toBe('read');
+    expect(command.browser).toBe(true);
+    expect(command.strategy).toBe('public');
+    expect(command.domain).toBe('html.duckduckgo.com');
+  });
+
+  it('should define keyword positional arg', () => {
+    const kwArg = command.args.find(a => a.name === 'keyword');
+    expect(kwArg).toBeDefined();
+    expect(kwArg.positional).toBe(true);
+    expect(kwArg.required).toBe(true);
+  });
+
+  it('should define limit arg with default 10', () => {
+    const limitArg = command.args.find(a => a.name === 'limit');
+    expect(limitArg).toBeDefined();
+    expect(limitArg.type).toBe('int');
+    expect(limitArg.default).toBe(10);
+  });
+
+  it('should define columns for output', () => {
+    expect(command.columns).toContain('rank');
+    expect(command.columns).toContain('title');
+    expect(command.columns).toContain('url');
+    expect(command.columns).toContain('snippet');
+    expect(command.columns).toContain('displayUrl');
+    expect(command.columns).toContain('icon');
+    expect(command.columns).toContain('resultType');
+  });
+
+  it('rejects empty query and out-of-range pagination before navigation', async () => {
+    const page = createPageMock();
+    await expect(command.func(page, { keyword: ' ', limit: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func(page, { keyword: 'opencli', limit: 11 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func(page, { keyword: 'opencli', limit: 5, offset: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('decodes DuckDuckGo redirect URLs and assigns listing rank', async () => {
+    const page = createPageMock([
+      [
+        'OpenCLI',
+        '/l/?uddg=https%3A%2F%2Fgithub.com%2Fjackwener%2FOpenCLI',
+        'CLI browser tooling',
+        'github.com/jackwener/OpenCLI',
+        '',
+        'web',
+      ],
+    ]);
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1 })).resolves.toEqual([{
+      rank: 1,
+      title: 'OpenCLI',
+      url: 'https://github.com/jackwener/OpenCLI',
+      snippet: 'CLI browser tooling',
+      displayUrl: 'github.com/jackwener/OpenCLI',
+      icon: '',
+      resultType: 'web',
+    }]);
+  });
+
+  it('executes the DOM extractor, filters ads, and returns canonical rows', async () => {
+    const dom = new JSDOM(`
+      <div class="result result--ad">
+        <a class="result__a" href="https://ads.example/">Sponsored result</a>
+      </div>
+      <div class="result">
+        <a class="result__a" href="/l/?uddg=https%3A%2F%2Fexample.com%2Farticle">Organic result</a>
+        <a class="result__snippet">Organic snippet</a>
+        <span class="result__url">example.com/article</span>
+        <img class="result__icon__img" src="https://icons.duckduckgo.com/ip3/example.com.ico">
+      </div>
+    `);
+    const page = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      wait: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn(async (source) => Function('document', `return ${source};`)(dom.window.document)),
+    };
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 5 })).resolves.toEqual([{
+      rank: 1,
+      title: 'Organic result',
+      url: 'https://example.com/article',
+      snippet: 'Organic snippet',
+      displayUrl: 'example.com/article',
+      icon: 'https://icons.duckduckgo.com/ip3/example.com.ico',
+      resultType: 'web',
+    }]);
+  });
+
+  it('unwraps browser envelopes for paginated extraction', async () => {
+    const page = createPageMock({ session: 'site:duckduckgo', data: [
+      ['Result', 'https://example.com/', 'snippet', 'example.com', '', 'web'],
+    ] });
+
+    const result = await command.func(page, { keyword: 'opencli', limit: 1, offset: 10 });
+
+    expect(result[0]).toMatchObject({ rank: 11, url: 'https://example.com/' });
+  });
+
+  it('fails typed instead of returning [] for malformed extraction payloads', async () => {
+    const page = createPageMock({ rows: [] });
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1 })).rejects.toMatchObject({
+      code: 'COMMAND_EXEC',
+      message: expect.stringContaining('payload shape'),
+    });
+  });
+});

package/clis/duckduckgo/suggest.js

@@ -0,0 +1,45 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { requireBoundedInteger, requireSearchQuery } from '../_shared/search-adapter.js';
+
+const command = cli({
+  site: 'duckduckgo',
+  name: 'suggest',
+  access: 'read',
+  description: 'DuckDuckGo search suggestions',
+  domain: 'duckduckgo.com',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'keyword', positional: true, required: true, help: 'Search query prefix' },
+    { name: 'limit', type: 'int', default: 8, help: 'Max number of suggestions' },
+  ],
+  columns: ['phrase'],
+  func: async (kwargs) => {
+    const limit = requireBoundedInteger(kwargs.limit, 8, 1, 20, '--limit');
+    const keyword = encodeURIComponent(requireSearchQuery(kwargs.keyword));
+    const url = `https://duckduckgo.com/ac/?q=${keyword}&type=list`;
+    let resp;
+    try {
+      resp = await fetch(url);
+    } catch (err) {
+      throw new CommandExecutionError(`DuckDuckGo suggest request failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!resp.ok) {
+      throw new CommandExecutionError(`DuckDuckGo suggest returned HTTP ${resp.status}`);
+    }
+    let data;
+    try {
+      data = await resp.json();
+    } catch (err) {
+      throw new CommandExecutionError(`DuckDuckGo suggest returned malformed JSON: ${err?.message ?? err}`);
+    }
+    const phrases = Array.isArray(data) && data.length > 1 && Array.isArray(data[1]) ? data[1] : [];
+    return phrases
+      .filter((phrase) => typeof phrase === 'string' && phrase.trim())
+      .slice(0, limit)
+      .map(function(p) { return { phrase: p }; });
+  },
+});
+
+export const __test__ = { command };

package/clis/duckduckgo/suggest.test.js

@@ -0,0 +1,66 @@
+import { afterEach, describe, it, expect, vi } from 'vitest';
+
+const { __test__ } = await import('./suggest.js');
+const command = __test__.command;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('duckduckgo suggest', () => {
+  it('should register as a valid command', () => {
+    expect(command).toBeDefined();
+    expect(command.site).toBe('duckduckgo');
+    expect(command.name).toBe('suggest');
+    expect(command.access).toBe('read');
+    expect(command.browser).toBe(false);
+    expect(command.strategy).toBe('public');
+  });
+
+  it('should define keyword positional arg', () => {
+    const kwArg = command.args.find(a => a.name === 'keyword');
+    expect(kwArg).toBeDefined();
+    expect(kwArg.positional).toBe(true);
+    expect(kwArg.required).toBe(true);
+  });
+
+  it('should define limit arg with default 8', () => {
+    const limitArg = command.args.find(a => a.name === 'limit');
+    expect(limitArg).toBeDefined();
+    expect(limitArg.default).toBe(8);
+  });
+
+  it('should define phrase column', () => {
+    expect(command.columns).toEqual(['phrase']);
+  });
+
+  it('rejects empty query and invalid limit before fetch', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    await expect(command.func({ keyword: '', limit: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func({ keyword: 'opencli', limit: 21 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns filtered suggestion rows from the public API payload', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+      json: async () => ['open', ['opencli', '', 'open source']],
+    });
+
+    await expect(command.func({ keyword: 'open', limit: 3 })).resolves.toEqual([
+      { phrase: 'opencli' },
+      { phrase: 'open source' },
+    ]);
+  });
+
+  it('maps fetch and malformed JSON failures to typed command errors', async () => {
+    vi.spyOn(globalThis, 'fetch').mockRejectedValueOnce(new Error('offline'));
+    await expect(command.func({ keyword: 'open', limit: 3 })).rejects.toMatchObject({ code: 'COMMAND_EXEC' });
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce({
+      ok: true,
+      json: async () => { throw new Error('bad json'); },
+    });
+    await expect(command.func({ keyword: 'open', limit: 3 })).rejects.toMatchObject({ code: 'COMMAND_EXEC' });
+  });
+});