@jackwener/opencli 1.5.8 → 1.5.9

package/src/clis/amazon/discussion.ts

@@ -0,0 +1,131 @@
+import { CommandExecutionError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  buildDiscussionUrl,
+  buildProvenance,
+  cleanText,
+  extractAsin,
+  normalizeProductUrl,
+  parseRatingValue,
+  parseReviewCount,
+  trimRatingPrefix,
+  uniqueNonEmpty,
+  assertUsableState,
+  gotoAndReadState,
+} from './shared.js';
+
+interface DiscussionPayload {
+  href?: string;
+  title?: string;
+  average_rating_text?: string | null;
+  total_review_count_text?: string | null;
+  qa_links?: string[];
+  review_samples?: Array<{
+    title?: string | null;
+    rating_text?: string | null;
+    author?: string | null;
+    date_text?: string | null;
+    body?: string | null;
+    verified?: boolean;
+  }>;
+}
+
+function normalizeDiscussionPayload(payload: DiscussionPayload): Record<string, unknown> {
+  const sourceUrl = cleanText(payload.href) || buildDiscussionUrl(payload.href ?? '');
+  const asin = extractAsin(payload.href ?? '') ?? null;
+  const averageRatingText = cleanText(payload.average_rating_text) || null;
+  const totalReviewCountText = cleanText(payload.total_review_count_text) || null;
+  const provenance = buildProvenance(sourceUrl);
+
+  return {
+    asin,
+    product_url: asin ? normalizeProductUrl(asin) : null,
+    discussion_url: sourceUrl,
+    ...provenance,
+    average_rating_text: averageRatingText,
+    average_rating_value: parseRatingValue(averageRatingText),
+    total_review_count_text: totalReviewCountText,
+    total_review_count: parseReviewCount(totalReviewCountText),
+    qa_urls: uniqueNonEmpty(payload.qa_links ?? []),
+    review_samples: (payload.review_samples ?? []).map((sample) => ({
+      title: trimRatingPrefix(sample.title) || null,
+      rating_text: cleanText(sample.rating_text) || null,
+      rating_value: parseRatingValue(sample.rating_text),
+      author: cleanText(sample.author) || null,
+      date_text: cleanText(sample.date_text) || null,
+      body: cleanText(sample.body) || null,
+      verified_purchase: sample.verified === true,
+    })),
+  };
+}
+
+async function readDiscussionPayload(page: IPage, input: string, limit: number): Promise<DiscussionPayload> {
+  const url = buildDiscussionUrl(input);
+  const state = await gotoAndReadState(page, url, 2500, 'discussion');
+  assertUsableState(state, 'discussion');
+
+  return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      title: document.title || '',
+      average_rating_text: document.querySelector('[data-hook="rating-out-of-text"]')?.textContent || '',
+      total_review_count_text: document.querySelector('[data-hook="total-review-count"]')?.textContent || '',
+      qa_links: Array.from(document.querySelectorAll('a[href*="ask/questions"]')).map((anchor) => anchor.href || ''),
+      review_samples: Array.from(document.querySelectorAll('[data-hook="review"]')).slice(0, ${limit}).map((card) => ({
+        title: card.querySelector('[data-hook="review-title"]')?.textContent || '',
+        rating_text:
+          card.querySelector('[data-hook="review-star-rating"]')?.textContent
+          || card.querySelector('[data-hook="cmps-review-star-rating"]')?.textContent
+          || '',
+        author: card.querySelector('.a-profile-name')?.textContent || '',
+        date_text: card.querySelector('[data-hook="review-date"]')?.textContent || '',
+        body: card.querySelector('[data-hook="review-body"]')?.textContent || '',
+        verified: !!card.querySelector('[data-hook="avp-badge"]'),
+      })),
+    }))()
+  `) as DiscussionPayload;
+}
+
+cli({
+  site: 'amazon',
+  name: 'discussion',
+  description: 'Amazon review summary and sample customer discussion from product review pages',
+  domain: 'amazon.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'input',
+      required: true,
+      positional: true,
+      help: 'ASIN or product URL, for example B0FJS72893',
+    },
+    {
+      name: 'limit',
+      type: 'int',
+      default: 10,
+      help: 'Maximum number of review samples to return (default 10)',
+    },
+  ],
+  columns: ['asin', 'average_rating_value', 'total_review_count'],
+  func: async (page, kwargs) => {
+    const input = String(kwargs.input ?? '');
+    const limit = Math.max(1, Number(kwargs.limit) || 10);
+    const payload = await readDiscussionPayload(page, input, limit);
+    const normalized = normalizeDiscussionPayload(payload);
+
+    if (!normalized.average_rating_text && !normalized.total_review_count_text) {
+      throw new CommandExecutionError(
+        'amazon discussion page did not expose review summary',
+        'The review page may have changed or hit a robot check. Open the review page in Chrome and retry.',
+      );
+    }
+
+    return [normalized];
+  },
+});
+
+export const __test__ = {
+  normalizeDiscussionPayload,
+};

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './offer.js';
+
+describe('amazon offer normalization', () => {
+  it('extracts sold-by and fulfillment facts from product offer text', () => {
+    const result = __test__.normalizeOfferPayload({
+      href: 'https://www.amazon.com/dp/B0FJS72893',
+      price_text: '$15.99',
+      merchant_info: '',
+      sold_by: 'KUATUDIRECT',
+      ships_from_text: 'Ships from Amazon',
+      offer_link: null,
+      review_url: 'https://www.amazon.com/dp/B0FJS72893#customerReviews',
+      qa_url: null,
+    });
+
+    expect(result.asin).toBe('B0FJS72893');
+    expect(result.sold_by).toBe('KUATUDIRECT');
+    expect(result.ships_from).toBe('Amazon');
+    expect(result.is_amazon_sold).toBe(false);
+    expect(result.is_amazon_fulfilled).toBe(true);
+  });
+
+  it('parses merchant info fallback text', () => {
+    expect(__test__.extractSoldBy('Sold by Example Seller and Fulfilled by Amazon.')).toBe('Example Seller');
+    expect(__test__.extractShipsFrom('Ships from Amazon')).toBe('Amazon');
+  });
+
+  it('detects delivery-location blocking in the buy box text', () => {
+    expect(__test__.isDeliveryLocationBlocked(
+      'This item cannot be shipped to your selected delivery location. Similar items shipping to Hong Kong',
+    )).toBe(true);
+    expect(__test__.isDeliveryLocationBlocked('Ships from Amazon')).toBe(false);
+  });
+});

package/src/clis/amazon/offer.ts

@@ -0,0 +1,185 @@
+import { CommandExecutionError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  buildProductUrl,
+  buildProvenance,
+  cleanText,
+  extractAsin,
+  isAmazonEntity,
+  normalizeProductUrl,
+  PRIMARY_PRICE_SELECTORS,
+  parsePriceText,
+  assertUsableState,
+  gotoAndReadState,
+} from './shared.js';
+
+interface OfferPayload {
+  href?: string;
+  title?: string;
+  price_text?: string | null;
+  merchant_info?: string | null;
+  sold_by?: string | null;
+  ships_from_text?: string | null;
+  offer_link?: string | null;
+  review_url?: string | null;
+  qa_url?: string | null;
+  buybox_text?: string | null;
+}
+
+const OFFER_FACT_SELECTOR = [
+  '#sellerProfileTriggerId',
+  '#shipsFromSoldByInsideBuyBox_feature_div',
+  '#fulfillerInfoFeature_feature_div',
+  '#merchantInfoFeature_feature_div',
+  '#tabular-buybox-container',
+  '#merchant-info',
+].join(', ');
+
+function collapseAdjacentWords(text: string): string {
+  const parts = cleanText(text).split(' ').filter(Boolean);
+  const deduped: string[] = [];
+  for (const part of parts) {
+    if (deduped[deduped.length - 1] === part) continue;
+    deduped.push(part);
+  }
+  return deduped.join(' ');
+}
+
+function extractShipsFrom(text: string): string | null {
+  const normalized = cleanText(text);
+  const match = normalized.match(/Ships from\s+(.+?)(?=Sold by|and Fulfilled by|$)/i);
+  return match ? collapseAdjacentWords(match[1].replace(/Ships from/ig, '')) : null;
+}
+
+function extractSoldBy(text: string): string | null {
+  const normalized = cleanText(text);
+  const match = normalized.match(/Sold by\s+(.+?)(?=and Fulfilled by|Ships from|$)/i);
+  return match ? collapseAdjacentWords(match[1]) : null;
+}
+
+function isDeliveryLocationBlocked(text: string | null | undefined): boolean {
+  const normalized = cleanText(text).toLowerCase();
+  return normalized.includes('cannot be shipped to your selected delivery location')
+    || normalized.includes('similar items shipping to')
+    || normalized.includes('deliver to hong kong');
+}
+
+function normalizeOfferPayload(payload: OfferPayload): Record<string, unknown> {
+  const asin = extractAsin(payload.href ?? '') ?? null;
+  const sourceUrl = cleanText(payload.href) || buildProductUrl(payload.href ?? '');
+  const price = parsePriceText(payload.price_text);
+  const merchantInfo = cleanText(payload.merchant_info) || null;
+  const soldBy = cleanText(payload.sold_by)
+    || extractSoldBy(payload.ships_from_text ?? '')
+    || extractSoldBy(merchantInfo ?? '')
+    || null;
+  const shipsFrom = extractShipsFrom(payload.ships_from_text ?? '')
+    || extractShipsFrom(merchantInfo ?? '')
+    || cleanText(payload.ships_from_text)
+    || null;
+  const provenance = buildProvenance(sourceUrl);
+
+  return {
+    asin,
+    product_url: normalizeProductUrl(payload.href),
+    ...provenance,
+    price_text: price.price_text,
+    price_value: price.price_value,
+    currency: price.currency,
+    merchant_info_text: merchantInfo,
+    sold_by: soldBy,
+    ships_from: shipsFrom,
+    offer_listing_url: cleanText(payload.offer_link) || null,
+    review_url: cleanText(payload.review_url) || null,
+    qa_url: cleanText(payload.qa_url) || null,
+    is_amazon_sold: isAmazonEntity(soldBy),
+    is_amazon_fulfilled: isAmazonEntity(shipsFrom) || /fulfilled by amazon/i.test(merchantInfo ?? ''),
+  };
+}
+
+async function readOfferPayload(page: IPage, input: string): Promise<OfferPayload> {
+  const url = buildProductUrl(input);
+  const state = await gotoAndReadState(page, url, 2500, 'offer');
+  assertUsableState(state, 'offer');
+
+  // Reconnecting to an existing Amazon target can surface the product page
+  // before the buy-box / merchant blocks are reattached to the DOM.
+  await page.wait({ selector: OFFER_FACT_SELECTOR, timeout: 6 }).catch(() => {});
+
+  return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      title: document.title || '',
+      price_text: (() => {
+        const selectors = ${JSON.stringify(PRIMARY_PRICE_SELECTORS)};
+        for (const selector of selectors) {
+          const text = document.querySelector(selector)?.textContent || '';
+          if (text.trim()) return text;
+        }
+        return '';
+      })(),
+      merchant_info: document.querySelector('#merchant-info')?.textContent || '',
+      sold_by: document.querySelector('#sellerProfileTriggerId')?.textContent || '',
+      ships_from_text:
+        document.querySelector('#shipsFromSoldByInsideBuyBox_feature_div')?.textContent
+        || document.querySelector('#fulfillerInfoFeature_feature_div')?.textContent
+        || document.querySelector('#merchantInfoFeature_feature_div')?.textContent
+        || document.querySelector('#tabular-buybox-container')?.textContent
+        || '',
+      offer_link: document.querySelector('a[href*="/gp/offer-listing/"]')?.href || '',
+      review_url: document.querySelector('a[href*="#customerReviews"]')?.href || '',
+      qa_url: document.querySelector('a[href*="ask/questions"]')?.href || '',
+      buybox_text:
+        document.querySelector('#desktop_qualifiedBuyBox')?.textContent
+        || document.querySelector('#buybox')?.textContent
+        || '',
+    }))()
+  `) as OfferPayload;
+}
+
+cli({
+  site: 'amazon',
+  name: 'offer',
+  description: 'Amazon seller, buy box, and fulfillment facts from the product page',
+  domain: 'amazon.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'input',
+      required: true,
+      positional: true,
+      help: 'ASIN or product URL, for example B0FJS72893',
+    },
+  ],
+  columns: ['asin', 'price_text', 'sold_by', 'ships_from', 'is_amazon_sold', 'is_amazon_fulfilled'],
+  func: async (page, kwargs) => {
+    const input = String(kwargs.input ?? '');
+    const payload = await readOfferPayload(page, input);
+    const normalized = normalizeOfferPayload(payload);
+
+    if (!normalized.sold_by && !normalized.ships_from && !normalized.merchant_info_text) {
+      if (isDeliveryLocationBlocked(payload.buybox_text)) {
+        throw new CommandExecutionError(
+          'amazon offer buy box is blocked by the current delivery location',
+          'The shared Chrome profile is not set to the target US delivery address. Switch Amazon delivery location to the requested US destination, reopen the product page, and retry.',
+        );
+      }
+
+      throw new CommandExecutionError(
+        'amazon offer surface did not expose seller or fulfillment facts',
+        'The product page may have changed. Open the product page in Chrome, make sure the buy box is visible, and retry.',
+      );
+    }
+
+    return [normalized];
+  },
+});
+
+export const __test__ = {
+  extractShipsFrom,
+  extractSoldBy,
+  isDeliveryLocationBlocked,
+  normalizeOfferPayload,
+};

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './product.js';
+
+describe('amazon product normalization', () => {
+  it('normalizes product facts from the product page', () => {
+    const result = __test__.normalizeProductPayload({
+      href: 'https://www.amazon.com/dp/B0FJS72893',
+      title: 'Amazon.com: KVTUKIAIT Desktop Shelf Organizer',
+      product_title: 'White Desktop Shelf Organizer for Top of Desk',
+      byline: 'Visit the KVTUKIAIT Store',
+      price_text: '$15.99',
+      rating_text: '3.9 out of 5 stars',
+      review_count_text: '27 ratings',
+      review_url: 'https://www.amazon.com/dp/B0FJS72893#customerReviews',
+      qa_url: null,
+      bullets: ['SPACE-SAVING DESK SHELF ORGANIZER', 'SMALL AND STYLISH AESTHETIC DECOR'],
+      breadcrumbs: ['Office Products', 'Desktop & Off-Surface Shelves'],
+    });
+
+    expect(result.asin).toBe('B0FJS72893');
+    expect(result.price_value).toBe(15.99);
+    expect(result.rating_value).toBe(3.9);
+    expect(result.review_count).toBe(27);
+    expect(result.breadcrumbs).toEqual(['Office Products', 'Desktop & Off-Surface Shelves']);
+  });
+});

package/src/clis/amazon/product.ts

@@ -0,0 +1,131 @@
+import { CommandExecutionError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  buildProductUrl,
+  buildProvenance,
+  cleanText,
+  extractAsin,
+  PRIMARY_PRICE_SELECTORS,
+  parsePriceText,
+  parseRatingValue,
+  parseReviewCount,
+  normalizeProductUrl,
+  uniqueNonEmpty,
+  assertUsableState,
+  gotoAndReadState,
+} from './shared.js';
+
+interface ProductPayload {
+  href?: string;
+  title?: string;
+  product_title?: string | null;
+  byline?: string | null;
+  price_text?: string | null;
+  rating_text?: string | null;
+  review_count_text?: string | null;
+  review_url?: string | null;
+  qa_url?: string | null;
+  bullets?: string[];
+  breadcrumbs?: string[];
+}
+
+const PRODUCT_TITLE_SELECTOR = '#productTitle, #title span, [data-feature-name="title"] h1 span';
+const BYLINE_SELECTOR = '#bylineInfo, [data-feature-name="bylineInfo"] #bylineInfo';
+
+function normalizeProductPayload(payload: ProductPayload): Record<string, unknown> {
+  const sourceUrl = cleanText(payload.href) || buildProductUrl(cleanText(payload.product_title) || cleanText(payload.href));
+  const asin = extractAsin(payload.href ?? '') ?? null;
+  const price = parsePriceText(payload.price_text);
+  const ratingText = cleanText(payload.rating_text) || null;
+  const reviewCountText = cleanText(payload.review_count_text) || null;
+  const provenance = buildProvenance(sourceUrl);
+
+  return {
+    asin,
+    title: cleanText(payload.product_title) || cleanText(payload.title) || null,
+    product_url: normalizeProductUrl(payload.href),
+    ...provenance,
+    brand_text: cleanText(payload.byline) || null,
+    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),
+    review_url: cleanText(payload.review_url) || null,
+    qa_url: cleanText(payload.qa_url) || null,
+    breadcrumbs: uniqueNonEmpty(payload.breadcrumbs ?? []),
+    bullet_points: uniqueNonEmpty(payload.bullets ?? []),
+  };
+}
+
+async function readProductPayload(page: IPage, input: string): Promise<ProductPayload> {
+  const url = buildProductUrl(input);
+  const state = await gotoAndReadState(page, url, 2500, 'product');
+  assertUsableState(state, 'product');
+
+  // Amazon can report a "stable" DOM before the product title block hydrates,
+  // especially when reconnecting to an existing shared CDP target.
+  await page.wait({ selector: PRODUCT_TITLE_SELECTOR, timeout: 6 }).catch(() => {});
+
+  return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      title: document.title || '',
+      product_title: document.querySelector(${JSON.stringify(PRODUCT_TITLE_SELECTOR)})?.textContent || '',
+      byline: document.querySelector(${JSON.stringify(BYLINE_SELECTOR)})?.textContent || '',
+      price_text: (() => {
+        const selectors = ${JSON.stringify(PRIMARY_PRICE_SELECTORS)};
+        for (const selector of selectors) {
+          const text = document.querySelector(selector)?.textContent || '';
+          if (text.trim()) return text;
+        }
+        return '';
+      })(),
+      rating_text:
+        document.querySelector('#acrPopover')?.getAttribute('title')
+        || document.querySelector('#acrPopover')?.textContent
+        || '',
+      review_count_text: document.querySelector('#acrCustomerReviewText')?.textContent || '',
+      review_url: document.querySelector('a[href*="#customerReviews"]')?.href || '',
+      qa_url: document.querySelector('a[href*="ask/questions"]')?.href || '',
+      bullets: Array.from(document.querySelectorAll('#feature-bullets li .a-list-item')).map((node) => node.textContent || ''),
+      breadcrumbs: Array.from(document.querySelectorAll('#wayfinding-breadcrumbs_feature_div a')).map((node) => node.textContent || ''),
+    }))()
+  `) as ProductPayload;
+}
+
+cli({
+  site: 'amazon',
+  name: 'product',
+  description: 'Amazon product page facts for candidate validation',
+  domain: 'amazon.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'input',
+      required: true,
+      positional: true,
+      help: 'ASIN or product URL, for example B0FJS72893',
+    },
+  ],
+  columns: ['asin', 'title', 'price_text', 'rating_value', 'review_count'],
+  func: async (page, kwargs) => {
+    const input = String(kwargs.input ?? '');
+    const payload = await readProductPayload(page, input);
+    if (!cleanText(payload.product_title)) {
+      throw new CommandExecutionError(
+        'amazon product page did not expose product content',
+        'The product page may have changed or hit a robot check. Open the product page in Chrome and retry.',
+      );
+    }
+    return [normalizeProductPayload(payload)];
+  },
+});
+
+export const __test__ = {
+  normalizeProductPayload,
+};

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

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './search.js';
+
+describe('amazon search normalization', () => {
+  it('normalizes search cards into research-friendly fields', () => {
+    const result = __test__.normalizeSearchCandidate({
+      asin: 'B0FJS72893',
+      title: 'White Desktop Shelf Organizer for Top of Desk',
+      href: 'https://www.amazon.com/KVTUKIAIT-White-Desktop-Shelf-Organizer/dp/B0FJS72893/ref=sr_1_1',
+      price_text: '$15.99',
+      rating_text: '3.9 out of 5 stars, rating details',
+      review_count_text: '(27)',
+      sponsored: false,
+      badge_texts: ['Limited time deal'],
+    }, 1, 'https://www.amazon.com/s?k=desk+shelf+organizer');
+
+    expect(result.asin).toBe('B0FJS72893');
+    expect(result.product_url).toBe('https://www.amazon.com/dp/B0FJS72893');
+    expect(result.price_value).toBe(15.99);
+    expect(result.rating_value).toBe(3.9);
+    expect(result.review_count).toBe(27);
+    expect(result.badges).toEqual(['Limited time deal']);
+  });
+});

package/src/clis/amazon/search.ts

@@ -0,0 +1,128 @@
+import { CommandExecutionError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  buildProvenance,
+  buildSearchUrl,
+  cleanText,
+  extractAsin,
+  normalizeProductUrl,
+  parsePriceText,
+  parseRatingValue,
+  parseReviewCount,
+  assertUsableState,
+  gotoAndReadState,
+} from './shared.js';
+
+interface SearchPayload {
+  href?: string;
+  cards?: Array<{
+    asin?: string;
+    title?: string;
+    href?: string;
+    price_text?: string | null;
+    rating_text?: string | null;
+    review_count_text?: string | null;
+    sponsored?: boolean;
+    badge_texts?: string[];
+  }>;
+}
+
+function normalizeSearchCandidate(
+  candidate: NonNullable<SearchPayload['cards']>[number],
+  rank: number,
+  sourceUrl: string,
+): Record<string, unknown> {
+  const productUrl = normalizeProductUrl(candidate.href);
+  const asin = extractAsin(candidate.asin ?? '') ?? extractAsin(productUrl ?? '') ?? null;
+  const price = parsePriceText(candidate.price_text);
+  const ratingText = cleanText(candidate.rating_text) || null;
+  const reviewCountText = cleanText(candidate.review_count_text) || null;
+  const provenance = buildProvenance(sourceUrl);
+
+  return {
+    rank,
+    asin,
+    title: cleanText(candidate.title) || null,
+    product_url: productUrl,
+    ...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),
+    is_sponsored: candidate.sponsored === true,
+    badges: (candidate.badge_texts ?? []).map((value) => cleanText(value)).filter(Boolean),
+  };
+}
+
+async function readSearchPayload(page: IPage, query: string): Promise<SearchPayload> {
+  const url = buildSearchUrl(query);
+  const state = await gotoAndReadState(page, url, 2500, 'search');
+  assertUsableState(state, 'search');
+
+  return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      cards: Array.from(document.querySelectorAll('[data-component-type="s-search-result"]'))
+        .map((card) => ({
+          asin: card.getAttribute('data-asin') || '',
+          title: card.querySelector('h2')?.textContent || '',
+          href: card.querySelector('a.a-link-normal[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 || '',
+          sponsored: /sponsored/i.test(card.innerText || ''),
+          badge_texts: Array.from(card.querySelectorAll('.a-badge-text')).map((node) => node.textContent || ''),
+        })),
+    }))()
+  `) as SearchPayload;
+}
+
+cli({
+  site: 'amazon',
+  name: 'search',
+  description: 'Amazon search results for product discovery and coarse filtering',
+  domain: 'amazon.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'query',
+      required: true,
+      positional: true,
+      help: 'Search query, for example "desk shelf organizer"',
+    },
+    {
+      name: 'limit',
+      type: 'int',
+      default: 20,
+      help: 'Maximum number of results to return (default 20)',
+    },
+  ],
+  columns: ['rank', 'asin', 'title', 'price_text', 'rating_value', 'review_count'],
+  func: async (page, kwargs) => {
+    const query = String(kwargs.query ?? '');
+    const limit = Math.max(1, Number(kwargs.limit) || 20);
+    const payload = await readSearchPayload(page, query);
+    const sourceUrl = cleanText(payload.href) || buildSearchUrl(query);
+    const cards = (payload.cards ?? [])
+      .filter((card) => cleanText(card.asin) && cleanText(card.title))
+      .slice(0, limit);
+
+    if (cards.length === 0) {
+      throw new CommandExecutionError(
+        'amazon search did not expose any product cards',
+        'The search page may have changed or hit a robot check. Open the same query in Chrome, verify the page is visible, and retry.',
+      );
+    }
+
+    return cards.map((card, index) => normalizeSearchCandidate(card, index + 1, sourceUrl));
+  },
+});
+
+export const __test__ = {
+  normalizeSearchCandidate,
+};