@jackwener/opencli 1.5.8 → 1.6.0

package/src/cli.ts

@@ -18,6 +18,13 @@ import { registerAllCommands } from './commanderAdapter.js';
 import { EXIT_CODES, getErrorMessage } from './errors.js';
 import { daemonStatus, daemonStop, daemonRestart } from './commands/daemon.js';
 
+/** Create a browser page for operate commands. Uses 'operate' workspace for session persistence. */
+async function getOperatePage(): Promise<import('./types.js').IPage> {
+  const { BrowserBridge } = await import('./browser/index.js');
+  const bridge = new BrowserBridge();
+  return bridge.connect({ timeout: 30, workspace: 'operate:default' });
+}
+
 export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
   const program = new Command();
   // enablePositionalOptions: prevents parent from consuming flags meant for subcommands;
@@ -229,6 +236,391 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       console.log(renderCascadeResult(result));
     });
 
+  // ── Built-in: operate (browser control for Claude Code skill) ───────────────
+  //
+  // Make websites accessible for AI agents.
+  // All commands wrapped in operateAction() for consistent error handling.
+
+  const operate = program
+    .command('operate')
+    .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+
+  /** Wrap operate actions with error handling and optional --json output */
+  function operateAction(fn: (page: Awaited<ReturnType<typeof getOperatePage>>, ...args: any[]) => Promise<unknown>) {
+    return async (...args: any[]) => {
+      try {
+        const page = await getOperatePage();
+        await fn(page, ...args);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Extension not connected') || msg.includes('Daemon')) {
+          console.error(`Browser not connected. Run 'opencli doctor' to diagnose.`);
+        } else if (msg.includes('attach failed') || msg.includes('chrome-extension://')) {
+          console.error(`Browser attach failed — another extension may be interfering. Try disabling 1Password.`);
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      }
+    };
+  }
+
+  // ── Navigation ──
+
+  /** Network interceptor JS — injected on every open/navigate to capture fetch/XHR */
+  const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=50000,F=window.fetch;window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();if(window.__opencli_net.length<M){var b=null;if(t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),method:(arguments[1]&&arguments[1].method)||'GET',status:r.status,size:t.length,ct:ct,body:b})}}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if((ct.includes('json')||ct.includes('text'))&&window.__opencli_net.length<M){var t=x.responseText,b=null;if(t&&t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:x._ou,method:x._om||'GET',status:x.status,size:t?t.length:0,ct:ct,body:b})}}catch(e){}});return S.apply(this,arguments)}})()`;
+
+  operate.command('open').argument('<url>').description('Open URL in automation window')
+    .action(operateAction(async (page, url) => {
+      await page.goto(url);
+      await page.wait(2);
+      // Auto-inject network interceptor for API discovery
+      try { await page.evaluate(NETWORK_INTERCEPTOR_JS); } catch { /* non-fatal */ }
+      console.log(`Navigated to: ${await page.getCurrentUrl?.() ?? url}`);
+    }));
+
+  operate.command('back').description('Go back in browser history')
+    .action(operateAction(async (page) => {
+      await page.evaluate('history.back()');
+      await page.wait(2);
+      console.log('Navigated back');
+    }));
+
+  operate.command('scroll').argument('<direction>', 'up or down').option('--amount <pixels>', 'Pixels to scroll', '500')
+    .description('Scroll page')
+    .action(operateAction(async (page, direction, opts) => {
+      if (direction !== 'up' && direction !== 'down') {
+        console.error(`Invalid direction "${direction}". Use "up" or "down".`);
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
+        return;
+      }
+      await page.scroll(direction, parseInt(opts.amount, 10));
+      console.log(`Scrolled ${direction}`);
+    }));
+
+  // ── Inspect ──
+
+  operate.command('state').description('Page state: URL, title, interactive elements with [N] indices')
+    .action(operateAction(async (page) => {
+      const snapshot = await page.snapshot({ viewportExpand: 800 });
+      const url = await page.getCurrentUrl?.() ?? '';
+      console.log(`URL: ${url}\n`);
+      console.log(typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2));
+    }));
+
+  operate.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)')
+    .description('Take screenshot')
+    .action(operateAction(async (page, path) => {
+      if (path) {
+        await page.screenshot({ path });
+        console.log(`Screenshot saved to: ${path}`);
+      } else {
+        console.log(await page.screenshot({ format: 'png' }));
+      }
+    }));
+
+  // ── Get commands (structured data extraction) ──
+
+  const get = operate.command('get').description('Get page properties');
+
+  get.command('title').description('Page title')
+    .action(operateAction(async (page) => {
+      console.log(await page.evaluate('document.title'));
+    }));
+
+  get.command('url').description('Current page URL')
+    .action(operateAction(async (page) => {
+      console.log(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
+    }));
+
+  get.command('text').argument('<index>', 'Element index').description('Element text content')
+    .action(operateAction(async (page, index) => {
+      const text = await page.evaluate(`document.querySelector('[data-opencli-ref="${index}"]')?.textContent?.trim()`);
+      console.log(text ?? '(empty)');
+    }));
+
+  get.command('value').argument('<index>', 'Element index').description('Input/textarea value')
+    .action(operateAction(async (page, index) => {
+      const val = await page.evaluate(`document.querySelector('[data-opencli-ref="${index}"]')?.value`);
+      console.log(val ?? '(empty)');
+    }));
+
+  get.command('html').option('--selector <css>', 'CSS selector scope').description('Page HTML (or scoped)')
+    .action(operateAction(async (page, opts) => {
+      const sel = opts.selector ? JSON.stringify(opts.selector) : 'null';
+      const html = await page.evaluate(`(${sel} ? document.querySelector(${sel})?.outerHTML : document.documentElement.outerHTML)?.slice(0, 50000)`);
+      console.log(html ?? '(empty)');
+    }));
+
+  get.command('attributes').argument('<index>', 'Element index').description('Element attributes')
+    .action(operateAction(async (page, index) => {
+      const attrs = await page.evaluate(`JSON.stringify(Object.fromEntries([...document.querySelector('[data-opencli-ref="${index}"]')?.attributes].map(a=>[a.name,a.value])))`);
+      console.log(attrs ?? '{}');
+    }));
+
+  // ── Interact ──
+
+  operate.command('click').argument('<index>', 'Element index from state').description('Click element by index')
+    .action(operateAction(async (page, index) => {
+      await page.click(index);
+      console.log(`Clicked element [${index}]`);
+    }));
+
+  operate.command('type').argument('<index>', 'Element index').argument('<text>', 'Text to type')
+    .description('Click element, then type text')
+    .action(operateAction(async (page, index, text) => {
+      await page.click(index);
+      await page.wait(0.3);
+      await page.typeText(index, text);
+      console.log(`Typed "${text}" into element [${index}]`);
+    }));
+
+  operate.command('select').argument('<index>', 'Element index of <select>').argument('<option>', 'Option text')
+    .description('Select dropdown option')
+    .action(operateAction(async (page, index, option) => {
+      const result = await page.evaluate(`
+        (function() {
+          var sel = document.querySelector('[data-opencli-ref="${index}"]');
+          if (!sel || sel.tagName !== 'SELECT') return { error: 'Not a <select>' };
+          var match = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
+          if (!match) return { error: 'Option not found', available: Array.from(sel.options).map(o => o.text.trim()) };
+          var setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+          if (setter) setter.call(sel, match.value); else sel.value = match.value;
+          sel.dispatchEvent(new Event('input', {bubbles:true}));
+          sel.dispatchEvent(new Event('change', {bubbles:true}));
+          return { selected: match.text };
+        })()
+      `) as { error?: string; selected?: string; available?: string[] } | null;
+      if (result?.error) {
+        console.error(`Error: ${result.error}${result.available ? ` — Available: ${result.available.join(', ')}` : ''}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      } else {
+        console.log(`Selected "${result?.selected}" in element [${index}]`);
+      }
+    }));
+
+  operate.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)')
+    .description('Press keyboard key')
+    .action(operateAction(async (page, key) => {
+      await page.pressKey(key);
+      console.log(`Pressed: ${key}`);
+    }));
+
+  // ── Wait commands ──
+
+  operate.command('wait')
+    .argument('<type>', 'selector, text, or time')
+    .argument('[value]', 'CSS selector, text string, or seconds')
+    .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
+    .description('Wait for selector, text, or time (e.g. wait selector ".loaded", wait text "Success", wait time 3)')
+    .action(operateAction(async (page, type, value, opts) => {
+      const timeout = parseInt(opts.timeout, 10);
+      if (type === 'time') {
+        const seconds = parseFloat(value ?? '2');
+        await page.wait(seconds);
+        console.log(`Waited ${seconds}s`);
+      } else if (type === 'selector') {
+        if (!value) { console.error('Missing CSS selector'); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        await page.wait({ selector: value, timeout: timeout / 1000 });
+        console.log(`Element "${value}" appeared`);
+      } else if (type === 'text') {
+        if (!value) { console.error('Missing text'); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        await page.wait({ text: value, timeout: timeout / 1000 });
+        console.log(`Text "${value}" appeared`);
+      } else {
+        console.error(`Unknown wait type "${type}". Use: selector, text, or time`);
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
+      }
+    }));
+
+  // ── Extract ──
+
+  operate.command('eval').argument('<js>', 'JavaScript code').description('Execute JS in page context, return result')
+    .action(operateAction(async (page, js) => {
+      const result = await page.evaluate(js);
+      if (typeof result === 'string') console.log(result);
+      else console.log(JSON.stringify(result, null, 2));
+    }));
+
+  // ── Network (API discovery) ──
+
+  operate.command('network')
+    .option('--detail <index>', 'Show full response body of request at index')
+    .option('--all', 'Show all requests including static resources')
+    .description('Show captured network requests (auto-captured since last open)')
+    .action(operateAction(async (page, opts) => {
+      const requests = await page.evaluate(`(function(){
+        var reqs = window.__opencli_net || [];
+        return JSON.stringify(reqs);
+      })()`) as string;
+
+      let items: Array<{ url: string; method: string; status: number; size: number; ct: string; body: unknown }> = [];
+      try { items = JSON.parse(requests); } catch { console.log('No network data captured. Run "operate open <url>" first.'); return; }
+
+      if (items.length === 0) { console.log('No requests captured.'); return; }
+
+      // Filter out static resources unless --all
+      if (!opts.all) {
+        items = items.filter(r =>
+          (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
+          !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
+          !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url)
+        );
+      }
+
+      if (opts.detail !== undefined) {
+        const idx = parseInt(opts.detail, 10);
+        const req = items[idx];
+        if (!req) { console.error(`Request #${idx} not found. ${items.length} requests available.`); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        console.log(`${req.method} ${req.url}`);
+        console.log(`Status: ${req.status} | Size: ${req.size} | Type: ${req.ct}`);
+        console.log('---');
+        console.log(typeof req.body === 'string' ? req.body : JSON.stringify(req.body, null, 2));
+      } else {
+        console.log(`Captured ${items.length} API requests:\n`);
+        items.forEach((r, i) => {
+          const bodyPreview = r.body ? (typeof r.body === 'string' ? r.body.slice(0, 60) : JSON.stringify(r.body).slice(0, 60)) : '';
+          console.log(`  [${i}] ${r.method} ${r.status} ${r.url.slice(0, 80)}`);
+          if (bodyPreview) console.log(`      ${bodyPreview}...`);
+        });
+        console.log(`\nUse --detail <index> to see full response body.`);
+      }
+    }));
+
+  // ── Init (adapter scaffolding) ──
+
+  operate.command('init')
+    .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
+    .description('Generate adapter scaffold in ~/.opencli/clis/')
+    .action(async (name: string) => {
+      try {
+        const parts = name.split('/');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+          console.error('Name must be site/command format (e.g. hn/top)');
+          process.exitCode = EXIT_CODES.USAGE_ERROR;
+          return;
+        }
+        const [site, command] = parts;
+        if (!/^[a-zA-Z0-9_-]+$/.test(site) || !/^[a-zA-Z0-9_-]+$/.test(command)) {
+          console.error('Name parts must be alphanumeric/dash/underscore only');
+          process.exitCode = EXIT_CODES.USAGE_ERROR;
+          return;
+        }
+
+        const os = await import('node:os');
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const dir = path.join(os.homedir(), '.opencli', 'clis', site);
+        const filePath = path.join(dir, `${command}.ts`);
+
+        if (fs.existsSync(filePath)) {
+          console.log(`Adapter already exists: ${filePath}`);
+          return;
+        }
+
+        // Try to detect domain from last operate session
+        let domain = site;
+        try {
+          const page = await getOperatePage();
+          const url = await page.getCurrentUrl?.();
+          if (url) { try { domain = new URL(url).hostname; } catch {} }
+        } catch { /* no active session */ }
+
+        const template = `import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${site}',
+  name: '${command}',
+  description: '', // TODO: describe what this command does
+  domain: '${domain}',
+  strategy: Strategy.PUBLIC, // TODO: PUBLIC (no auth), COOKIE (needs login), UI (DOM interaction)
+  browser: false,            // TODO: set true if needs browser
+  args: [
+    { name: 'limit', type: 'int', default: 10, help: 'Number of items' },
+  ],
+  columns: [], // TODO: field names for table output (e.g. ['title', 'score', 'url'])
+  func: async (page, kwargs) => {
+    // TODO: implement data fetching
+    // Prefer API calls (fetch) over browser automation
+    // page is available if browser: true
+    return [];
+  },
+});
+`;
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, template, 'utf-8');
+        console.log(`Created: ${filePath}`);
+        console.log(`Edit the file to implement your adapter, then run: opencli operate verify ${name}`);
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      }
+    });
+
+  // ── Verify (test adapter) ──
+
+  operate.command('verify')
+    .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
+    .description('Execute an adapter and show results')
+    .action(async (name: string) => {
+      try {
+        const parts = name.split('/');
+        if (parts.length !== 2) { console.error('Name must be site/command format'); process.exitCode = EXIT_CODES.USAGE_ERROR; return; }
+        const [site, command] = parts;
+        if (!/^[a-zA-Z0-9_-]+$/.test(site) || !/^[a-zA-Z0-9_-]+$/.test(command)) {
+          console.error('Name parts must be alphanumeric/dash/underscore only');
+          process.exitCode = EXIT_CODES.USAGE_ERROR;
+          return;
+        }
+
+        const { execSync } = await import('node:child_process');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.ts`);
+
+        const fs = await import('node:fs');
+        if (!fs.existsSync(filePath)) {
+          console.error(`Adapter not found: ${filePath}`);
+          console.error(`Run "opencli operate init ${name}" to create it.`);
+          process.exitCode = EXIT_CODES.GENERIC_ERROR;
+          return;
+        }
+
+        console.log(`🔍 Verifying ${name}...\n`);
+        console.log(`  Loading: ${filePath}`);
+
+        try {
+          const output = execSync(`node dist/main.js ${site} ${command} --limit 3`, {
+            cwd: path.join(path.dirname(import.meta.url.replace('file://', '')), '..'),
+            timeout: 30000,
+            encoding: 'utf-8',
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          console.log(`  Executing: opencli ${site} ${command} --limit 3\n`);
+          console.log(output);
+          console.log(`\n  ✓ Adapter works!`);
+        } catch (err: any) {
+          console.log(`  Executing: opencli ${site} ${command} --limit 3\n`);
+          if (err.stdout) console.log(err.stdout);
+          if (err.stderr) console.error(err.stderr.slice(0, 500));
+          console.log(`\n  ✗ Adapter failed. Fix the code and try again.`);
+          process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+      }
+    });
+
+  // ── Session ──
+
+  operate.command('close').description('Close the automation window')
+    .action(operateAction(async (page) => {
+      await page.closeWindow?.();
+      console.log('Automation window closed');
+    }));
+
   // ── Built-in: doctor / completion ──────────────────────────────────────────
 
   program

package/src/clis/amazon/bestsellers.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './bestsellers.js';
+
+describe('amazon bestsellers normalization', () => {
+  it('normalizes bestseller cards and infers review counts from card text', () => {
+    const result = __test__.normalizeBestsellerCandidate({
+      asin: 'B0DR31GC3D',
+      title: '',
+      href: 'https://www.amazon.com/NUTIKAS-Shelves-Desktop-Orgnizer-Shlef/dp/B0DR31GC3D/ref=zg_bs',
+      price_text: '$25.92',
+      rating_text: '4.3 out of 5 stars',
+      review_count_text: '',
+      card_text: 'Desk Shelves Desktop Organizer Shlef\n4.3 out of 5 stars\n435\n$25.92',
+    }, 2, 'Amazon Best Sellers: Best Desktop & Off-Surface Shelves', 'https://www.amazon.com/example');
+
+    expect(result.rank).toBe(2);
+    expect(result.asin).toBe('B0DR31GC3D');
+    expect(result.title).toBe('Desk Shelves Desktop Organizer Shlef');
+    expect(result.review_count).toBe(435);
+    expect(result.list_title).toBe('Amazon Best Sellers: Best Desktop & Off-Surface Shelves');
+  });
+});

package/src/clis/amazon/bestsellers.ts

@@ -0,0 +1,180 @@
+import { CommandExecutionError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  buildProvenance,
+  cleanText,
+  extractAsin,
+  extractReviewCountFromCardText,
+  firstMeaningfulLine,
+  normalizeProductUrl,
+  parsePriceText,
+  parseRatingValue,
+  parseReviewCount,
+  resolveBestsellersUrl,
+  uniqueNonEmpty,
+  assertUsableState,
+  gotoAndReadState,
+} from './shared.js';
+
+interface BestsellersPagePayload {
+  href?: string;
+  title?: string;
+  list_title?: string;
+  cards?: Array<{
+    rank_text?: string | null;
+    asin?: string | null;
+    title?: string | null;
+    href?: string | null;
+    price_text?: string | null;
+    rating_text?: string | null;
+    review_count_text?: string | null;
+    card_text?: string | null;
+  }>;
+  page_links?: string[];
+}
+
+function normalizeBestsellerCandidate(
+  candidate: NonNullable<BestsellersPagePayload['cards']>[number],
+  rank: number,
+  listTitle: string | null,
+  sourceUrl: string,
+): Record<string, unknown> {
+  const productUrl = normalizeProductUrl(candidate.href);
+  const asin = extractAsin(candidate.asin ?? '') ?? extractAsin(productUrl ?? '') ?? null;
+  const title = cleanText(candidate.title) || firstMeaningfulLine(candidate.card_text);
+  const price = parsePriceText(cleanText(candidate.price_text) || candidate.card_text);
+  const ratingText = cleanText(candidate.rating_text) || null;
+  const reviewCountText = cleanText(candidate.review_count_text)
+    || extractReviewCountFromCardText(candidate.card_text)
+    || null;
+  const provenance = buildProvenance(sourceUrl);
+
+  return {
+    rank,
+    asin,
+    title: title || null,
+    product_url: productUrl,
+    list_title: listTitle,
+    ...provenance,
+    price_text: price.price_text,
+    price_value: price.price_value,
+    currency: price.currency,
+    rating_text: ratingText,
+    rating_value: parseRatingValue(ratingText),
+    review_count_text: reviewCountText,
+    review_count: parseReviewCount(reviewCountText),
+  };
+}
+
+async function readBestsellersPage(page: IPage, url: string): Promise<BestsellersPagePayload> {
+  const state = await gotoAndReadState(page, url, 2500, 'bestsellers');
+  assertUsableState(state, 'bestsellers');
+
+  return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      title: document.title || '',
+      list_title:
+        document.querySelector('#zg_banner_text')?.textContent
+        || document.querySelector('h1')?.textContent
+        || '',
+      cards: Array.from(document.querySelectorAll('.p13n-sc-uncoverable-faceout'))
+        .map((card) => ({
+          rank_text:
+            card.querySelector('.zg-bdg-text')?.textContent
+            || card.querySelector('[class*="rank"]')?.textContent
+            || '',
+          asin: card.id || '',
+          title:
+            card.querySelector('[class*="line-clamp"]')?.textContent
+            || card.querySelector('img')?.getAttribute('alt')
+            || '',
+          href: card.querySelector('a[href*="/dp/"]')?.href || '',
+          price_text: card.querySelector('.a-price .a-offscreen')?.textContent || '',
+          rating_text: card.querySelector('[aria-label*="out of 5 stars"]')?.getAttribute('aria-label') || '',
+          review_count_text:
+            card.querySelector('a[href*="#customerReviews"]')?.textContent
+            || card.querySelector('.a-size-small')?.textContent
+            || '',
+          card_text: card.innerText || '',
+        })),
+      page_links: Array.from(document.querySelectorAll('li.a-normal a, li.a-selected a'))
+        .map((anchor) => anchor.href || '')
+        .filter((href) => /\\/zgbs\\//.test(href) && /(?:[?&]pg=|ref=zg_bs_pg_)/.test(href)),
+    }))()
+  `) as BestsellersPagePayload;
+}
+
+cli({
+  site: 'amazon',
+  name: 'bestsellers',
+  description: 'Amazon Best Sellers pages for category candidate discovery',
+  domain: 'amazon.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'input',
+      positional: true,
+      help: 'Best sellers URL or /zgbs path. Omit to use the root Best Sellers page.',
+    },
+    {
+      name: 'limit',
+      type: 'int',
+      default: 100,
+      help: 'Maximum number of ranked items to return (default 100)',
+    },
+  ],
+  columns: ['rank', 'asin', 'title', 'price_text', 'rating_value', 'review_count'],
+  func: async (page, kwargs) => {
+    const limit = Math.max(1, Number(kwargs.limit) || 100);
+    const initialUrl = resolveBestsellersUrl(typeof kwargs.input === 'string' ? kwargs.input : undefined);
+
+    const queue = [initialUrl];
+    const visited = new Set<string>();
+    const seenAsins = new Set<string>();
+    const results: Record<string, unknown>[] = [];
+    let listTitle: string | null = null;
+
+    while (queue.length > 0 && results.length < limit) {
+      const nextUrl = queue.shift()!;
+      if (visited.has(nextUrl)) continue;
+      visited.add(nextUrl);
+
+      const payload = await readBestsellersPage(page, nextUrl);
+      const sourceUrl = cleanText(payload.href) || nextUrl;
+      listTitle = cleanText(payload.list_title) || cleanText(payload.title) || listTitle;
+      const cards = payload.cards ?? [];
+
+      for (const card of cards) {
+        const normalized = normalizeBestsellerCandidate(card, results.length + 1, listTitle, sourceUrl);
+        const asin = cleanText(String(normalized.asin ?? ''));
+        if (!asin || seenAsins.has(asin)) continue;
+        seenAsins.add(asin);
+        results.push(normalized);
+        if (results.length >= limit) break;
+      }
+
+      const pageLinks = uniqueNonEmpty(payload.page_links ?? []);
+      for (const href of pageLinks) {
+        if (!visited.has(href) && !queue.includes(href)) {
+          queue.push(href);
+        }
+      }
+    }
+
+    if (results.length === 0) {
+      throw new CommandExecutionError(
+        'amazon bestsellers did not expose any ranked items',
+        'Open the same best sellers page in Chrome, verify it is a real Amazon ranking page, and retry.',
+      );
+    }
+
+    return results.slice(0, limit);
+  },
+});
+
+export const __test__ = {
+  normalizeBestsellerCandidate,
+};

package/src/clis/amazon/discussion.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './discussion.js';
+
+describe('amazon discussion normalization', () => {
+  it('normalizes review summary and sample reviews', () => {
+    const result = __test__.normalizeDiscussionPayload({
+      href: 'https://www.amazon.com/product-reviews/B0FJS72893',
+      average_rating_text: '3.9 out of 5',
+      total_review_count_text: '27 global ratings',
+      qa_links: [],
+      review_samples: [
+        {
+          title: '5.0 out of 5 stars Great value and quality',
+          rating_text: '5.0 out of 5 stars',
+          author: 'GTreader2',
+          date_text: 'Reviewed in the United States on February 21, 2026',
+          body: 'Small but mighty.',
+          verified: true,
+        },
+      ],
+    });
+
+    expect(result.asin).toBe('B0FJS72893');
+    expect(result.average_rating_value).toBe(3.9);
+    expect(result.total_review_count).toBe(27);
+    expect(result.review_samples).toEqual([
+      {
+        title: 'Great value and quality',
+        rating_text: '5.0 out of 5 stars',
+        rating_value: 5,
+        author: 'GTreader2',
+        date_text: 'Reviewed in the United States on February 21, 2026',
+        body: 'Small but mighty.',
+        verified_purchase: true,
+      },
+    ]);
+  });
+});