@jackwener/opencli 1.7.11 → 1.7.13

package/clis/coingecko/derivatives.js

@@ -0,0 +1,84 @@
+// coingecko derivatives — perpetual / futures tickers across crypto exchanges.
+//
+// Hits the public `/api/v3/derivatives` endpoint (no auth, free tier). Each
+// row is one exchange-symbol combo: market, contract type, mark price, 24h
+// %, basis vs index, funding rate, open interest (USD), 24h volume.
+//
+// CoinGecko sorts the response by 24h volume desc, so `rank` mirrors the
+// listing order with no client-side reshuffling.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const ENDPOINT = 'https://api.coingecko.com/api/v3/derivatives';
+
+cli({
+    site: 'coingecko',
+    name: 'derivatives',
+    access: 'read',
+    description: 'Top crypto derivative (perpetual / futures) markets by 24h volume',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Max rows to return (1-500; CoinGecko returns one large page).' },
+        { name: 'symbol', type: 'string', required: false, help: 'Optional symbol substring filter (e.g. "BTC", "ETHUSDT").' },
+    ],
+    columns: ['rank', 'market', 'symbol', 'indexId', 'contractType', 'price', 'change24hPct', 'fundingRate', 'openInterestUsd', 'volume24hUsd', 'expired'],
+    func: async (args) => {
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('coingecko derivatives limit must be a positive integer');
+        }
+        if (limit > 500) {
+            throw new ArgumentError('coingecko derivatives limit must be <= 500');
+        }
+        const filter = args.symbol == null ? '' : String(args.symbol).trim().toUpperCase();
+        let resp;
+        try {
+            resp = await fetch(ENDPOINT, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko derivatives request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko derivatives returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko derivatives returned HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko derivatives returned malformed JSON: ${err?.message ?? err}`);
+        }
+        if (!Array.isArray(data) || !data.length) {
+            throw new EmptyResultError('coingecko derivatives', 'CoinGecko returned no derivative tickers.');
+        }
+        let rows = data;
+        if (filter) {
+            rows = data.filter((d) => String(d.symbol ?? '').toUpperCase().includes(filter)
+                || String(d.index_id ?? '').toUpperCase().includes(filter));
+            if (!rows.length) {
+                throw new EmptyResultError('coingecko derivatives', `No derivative tickers matched symbol="${filter}".`);
+            }
+        }
+        return rows.slice(0, limit).map((d, i) => ({
+            rank: i + 1,
+            market: String(d.market ?? ''),
+            symbol: String(d.symbol ?? ''),
+            indexId: String(d.index_id ?? ''),
+            contractType: String(d.contract_type ?? ''),
+            price: d.price != null ? Number(d.price) : null,
+            change24hPct: d.price_percentage_change_24h != null ? Number(d.price_percentage_change_24h) : null,
+            fundingRate: d.funding_rate != null ? Number(d.funding_rate) : null,
+            openInterestUsd: d.open_interest != null ? Number(d.open_interest) : null,
+            volume24hUsd: d.volume_24h != null ? Number(d.volume_24h) : null,
+            expired: d.expired_at ? String(d.expired_at) : '',
+        }));
+    },
+});

package/clis/coingecko/exchanges.js

@@ -0,0 +1,74 @@
+// coingecko exchanges — top crypto exchanges by 24h BTC trading volume.
+//
+// Hits the public `/api/v3/exchanges` endpoint. Returns the columns most
+// useful for an agent: trust score, 24h BTC volume, country, year founded,
+// canonical URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'exchanges',
+    access: 'read',
+    description: 'Top crypto exchanges by 24h BTC trading volume',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of exchanges (1-250, CoinGecko per_page upper bound)' },
+        { name: 'page', type: 'int', default: 1, help: 'Page number (1-based)' },
+    ],
+    columns: ['rank', 'id', 'name', 'trustScore', 'volume24hBtc', 'country', 'yearEstablished', 'url'],
+    func: async (args) => {
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('coingecko limit must be a positive integer');
+        }
+        if (limit > 250) {
+            throw new ArgumentError('coingecko limit must be <= 250 (per_page upper bound)');
+        }
+        const page = Number(args.page ?? 1);
+        if (!Number.isInteger(page) || page <= 0) {
+            throw new ArgumentError('coingecko page must be a positive integer');
+        }
+        const url = new URL('https://api.coingecko.com/api/v3/exchanges');
+        url.searchParams.set('per_page', String(limit));
+        url.searchParams.set('page', String(page));
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko exchanges request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko exchanges returned HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko exchanges returned malformed JSON: ${err?.message ?? err}`);
+        }
+        if (!Array.isArray(data) || !data.length) {
+            throw new EmptyResultError('coingecko exchanges', 'CoinGecko returned no exchange data.');
+        }
+        return data.map((ex, i) => ({
+            rank: (page - 1) * limit + i + 1,
+            id: String(ex.id ?? ''),
+            name: String(ex.name ?? ''),
+            trustScore: ex.trust_score != null ? Number(ex.trust_score) : null,
+            volume24hBtc: ex.trade_volume_24h_btc != null ? Number(ex.trade_volume_24h_btc) : null,
+            country: String(ex.country ?? ''),
+            yearEstablished: ex.year_established != null ? Number(ex.year_established) : null,
+            url: String(ex.url ?? ''),
+        }));
+    },
+});

package/clis/coingecko/global.js

@@ -0,0 +1,71 @@
+// coingecko global — total crypto market cap, volume, BTC/ETH dominance,
+// active currencies, ICO counts, in a single row.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'global',
+    access: 'read',
+    description: 'Aggregate crypto market stats: total market cap, volume, dominance',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'currency', type: 'string', default: 'usd', help: 'Quote currency for total market cap / volume (usd, cny, eur, jpy, ...)' },
+    ],
+    columns: ['currency', 'totalMarketCap', 'totalVolume24h', 'marketCapChange24hPct', 'btcDominancePct', 'ethDominancePct', 'activeCryptocurrencies', 'markets', 'ongoingIcos', 'updatedAt'],
+    func: async (args) => {
+        const currency = String(args.currency ?? 'usd').trim().toLowerCase();
+        if (!/^[a-z0-9-]{2,20}$/.test(currency)) {
+            throw new ArgumentError(`coingecko currency must look like a currency slug (got "${args.currency}")`);
+        }
+        let resp;
+        try {
+            resp = await fetch('https://api.coingecko.com/api/v3/global', { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko global request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko global returned HTTP ${resp.status}`);
+        }
+        let body;
+        try {
+            body = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko global returned malformed JSON: ${err?.message ?? err}`);
+        }
+        const data = body?.data;
+        if (!data) {
+            throw new CommandExecutionError('coingecko global returned no data envelope');
+        }
+        const totalMarketCap = data?.total_market_cap?.[currency];
+        const totalVolume = data?.total_volume?.[currency];
+        if (totalMarketCap == null && totalVolume == null) {
+            throw new ArgumentError(
+                `coingecko has no market totals for currency "${currency}"`,
+                'Use a CoinGecko-supported quote currency such as usd, cny, eur, or jpy.',
+            );
+        }
+        return [{
+            currency: currency.toUpperCase(),
+            totalMarketCap: totalMarketCap != null ? Number(totalMarketCap) : null,
+            totalVolume24h: totalVolume != null ? Number(totalVolume) : null,
+            marketCapChange24hPct: data.market_cap_change_percentage_24h_usd != null ? Number(data.market_cap_change_percentage_24h_usd) : null,
+            btcDominancePct: data?.market_cap_percentage?.btc != null ? Number(data.market_cap_percentage.btc) : null,
+            ethDominancePct: data?.market_cap_percentage?.eth != null ? Number(data.market_cap_percentage.eth) : null,
+            activeCryptocurrencies: data.active_cryptocurrencies != null ? Number(data.active_cryptocurrencies) : null,
+            markets: data.markets != null ? Number(data.markets) : null,
+            ongoingIcos: data.ongoing_icos != null ? Number(data.ongoing_icos) : null,
+            updatedAt: data.updated_at ? new Date(data.updated_at * 1000).toISOString() : '',
+        }];
+    },
+});

package/clis/coingecko/top.js

@@ -0,0 +1,64 @@
+// coingecko top — top coins by market cap.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+cli({
+  site: 'coingecko',
+  name: 'top',
+  access: 'read',
+  description: '按市值排序的加密货币行情（默认 USD）',
+  domain: 'api.coingecko.com',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'currency', type: 'string', default: 'usd', help: '计价币种 (usd / cny / eur / jpy ...)' },
+    { name: 'limit',    type: 'int',    default: 10,    help: '返回数量（默认 10，最多 250）' },
+  ],
+  columns: ['rank', 'symbol', 'name', 'price', 'change24hPct', 'marketCap', 'volume24h', 'high24h', 'low24h'],
+  func: async (args) => {
+    const currency = String(args.currency ?? 'usd').toLowerCase();
+    const limit = Number(args.limit ?? 10);
+    if (!Number.isInteger(limit) || limit <= 0) {
+      throw new ArgumentError('limit must be a positive integer');
+    }
+    if (limit > 250) {
+      throw new ArgumentError('limit must be <= 250 (CoinGecko per_page upper bound)');
+    }
+
+    const url = new URL('https://api.coingecko.com/api/v3/coins/markets');
+    url.searchParams.set('vs_currency', currency);
+    url.searchParams.set('order', 'market_cap_desc');
+    url.searchParams.set('per_page', String(limit));
+    url.searchParams.set('page', '1');
+    url.searchParams.set('sparkline', 'false');
+
+    let resp;
+    try {
+      resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+    } catch (error) {
+      throw new CommandExecutionError(`coingecko top request failed: ${error?.message || error}`);
+    }
+    if (!resp.ok) throw new CommandExecutionError(`coingecko top failed: HTTP ${resp.status}`);
+    let data;
+    try {
+      data = await resp.json();
+    } catch (error) {
+      throw new CommandExecutionError(`coingecko returned malformed JSON: ${error?.message || error}`);
+    }
+    if (data?.error) throw new CommandExecutionError(`coingecko returned error: ${data.error}`);
+    if (!Array.isArray(data)) throw new CommandExecutionError('coingecko returned an unexpected response');
+    if (data.length === 0) throw new EmptyResultError('coingecko top', 'coingecko returned no market data');
+
+    return data.map((c) => ({
+      rank: c.market_cap_rank,
+      symbol: String(c.symbol ?? '').toUpperCase(),
+      name: c.name,
+      price: c.current_price,
+      change24hPct: c.price_change_percentage_24h,
+      marketCap: c.market_cap,
+      volume24h: c.total_volume,
+      high24h: c.high_24h,
+      low24h: c.low_24h,
+    }));
+  },
+});

package/clis/coingecko/trending.js

@@ -0,0 +1,55 @@
+// coingecko trending — top trending coins on CoinGecko (by user search activity).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'trending',
+    access: 'read',
+    description: 'Top trending cryptocurrencies on CoinGecko in the last 24h (search-volume based).',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['rank', 'id', 'symbol', 'name', 'marketCapRank', 'priceBtc', 'thumb'],
+    func: async () => {
+        const url = 'https://api.coingecko.com/api/v3/search/trending';
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        } catch (error) {
+            throw new CommandExecutionError(`coingecko trending request failed: ${error?.message || error}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError('coingecko returned HTTP 429 (rate limited)', 'Wait and retry.');
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko trending failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`coingecko returned malformed JSON: ${error?.message || error}`);
+        }
+        const coins = Array.isArray(data?.coins) ? data.coins : [];
+        if (coins.length === 0) {
+            throw new EmptyResultError('coingecko trending', 'coingecko returned no trending coins.');
+        }
+        return coins.map((entry, i) => {
+            const c = entry?.item || {};
+            return {
+                rank: i + 1,
+                id: c.id || '',
+                symbol: String(c.symbol || '').toUpperCase(),
+                name: c.name || '',
+                marketCapRank: c.market_cap_rank ?? null,
+                priceBtc: c.price_btc ?? null,
+                thumb: c.thumb || c.small || c.large || '',
+            };
+        });
+    },
+});

package/clis/coupang/add-to-cart.js

@@ -1,5 +1,6 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { canonicalizeProductUrl, normalizeProductId } from './utils.js';
+import { canonicalizeProductUrl, normalizeProductId, requireProductIdArg } from './utils.js';
 function escapeJsString(value) {
     return JSON.stringify(value);
 }
@@ -94,6 +95,7 @@ function buildAddToCartEvaluate(expectedProductId) {
 cli({
     site: 'coupang',
     name: 'add-to-cart',
+    access: 'write',
     description: 'Add a Coupang product to cart using logged-in browser session',
     domain: 'www.coupang.com',
     strategy: Strategy.COOKIE,
@@ -104,31 +106,38 @@ cli({
     ],
     columns: ['ok', 'product_id', 'url', 'message'],
     func: async (page, kwargs) => {
-        const rawProductId = kwargs['product-id'] ?? kwargs['product-id'];
-        const productId = normalizeProductId(rawProductId);
-        const targetUrl = canonicalizeProductUrl(kwargs.url, productId);
-        if (!productId && !targetUrl) {
-            throw new Error('Either --product-id or --url is required');
+        const rawProductId = kwargs['product-id'];
+        if (!rawProductId && !kwargs.url) {
+            throw new ArgumentError('Either --product-id or --url is required');
         }
+        const productId = rawProductId
+            ? requireProductIdArg(rawProductId, 'product-id')
+            : requireProductIdArg(kwargs.url, '--url');
+        const targetUrl = canonicalizeProductUrl(kwargs.url, productId);
         const finalUrl = targetUrl || canonicalizeProductUrl('', productId);
-        await page.goto(finalUrl);
-        const result = await page.evaluate(buildAddToCartEvaluate(productId));
+        await page.goto(finalUrl).catch((error) => {
+            throw new CommandExecutionError(`coupang add-to-cart navigation failed: ${error?.message || error}`);
+        });
+        const result = await page.evaluate(buildAddToCartEvaluate(productId)).catch((error) => {
+            throw new CommandExecutionError(`coupang add-to-cart evaluation failed: ${error?.message || error}`);
+        });
         const loginHints = result?.loginHints ?? {};
         if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
-            throw new Error('Coupang login required. Please log into Coupang in Chrome and retry.');
+            throw new AuthRequiredError('coupang.com', 'Please log into Coupang in Chrome and retry.');
         }
         const actualProductId = normalizeProductId(result?.currentProductId || productId);
         if (result?.reason === 'PRODUCT_MISMATCH') {
-            throw new Error(`Product mismatch: expected ${productId}, got ${actualProductId || 'unknown'}`);
+            const observed = actualProductId ? `got ${actualProductId}` : 'no product id observed';
+            throw new CommandExecutionError(`Product mismatch: expected ${productId}, ${observed}`);
         }
         if (result?.reason === 'OPTION_REQUIRED') {
-            throw new Error('This product requires option selection and is not supported in v1.');
+            throw new CommandExecutionError('This product requires option selection and is not supported in v1.');
         }
         if (result?.reason === 'ADD_TO_CART_BUTTON_NOT_FOUND') {
-            throw new Error('Could not find an add-to-cart button on the product page.');
+            throw new CommandExecutionError('Could not find an add-to-cart button on the product page.');
         }
         if (!result?.ok) {
-            throw new Error('Failed to confirm add-to-cart success.');
+            throw new CommandExecutionError('Failed to confirm add-to-cart success.');
         }
         return [{
                 ok: true,

package/clis/coupang/coupang.test.js

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './search.js';
+import './product.js';
+import './add-to-cart.js';
+import { parseLimitArg, parsePageArg, requireProductIdArg } from './utils.js';
+
+describe('coupang utils — parseLimitArg / parsePageArg (no silent clamp)', () => {
+    it('parseLimitArg returns fallback for empty / undefined', () => {
+        expect(parseLimitArg(undefined, 20, 50)).toBe(20);
+        expect(parseLimitArg(null, 20, 50)).toBe(20);
+        expect(parseLimitArg('', 20, 50)).toBe(20);
+    });
+
+    it('parseLimitArg accepts integers in range', () => {
+        expect(parseLimitArg(1, 20, 50)).toBe(1);
+        expect(parseLimitArg(50, 20, 50)).toBe(50);
+        expect(parseLimitArg('25', 20, 50)).toBe(25);
+    });
+
+    it('parseLimitArg throws ArgumentError on out-of-range / non-integer (no silent clamp)', () => {
+        expect(() => parseLimitArg(0, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(-1, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(51, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(999, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg('abc', 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(1.5, 20, 50)).toThrow(ArgumentError);
+    });
+
+    it('parsePageArg returns fallback for empty', () => {
+        expect(parsePageArg(undefined, 1)).toBe(1);
+        expect(parsePageArg('', 1)).toBe(1);
+    });
+
+    it('parsePageArg accepts positive integers', () => {
+        expect(parsePageArg(1, 1)).toBe(1);
+        expect(parsePageArg('5', 1)).toBe(5);
+    });
+
+    it('parsePageArg throws ArgumentError on non-positive (no silent lift to 1)', () => {
+        expect(() => parsePageArg(0, 1)).toThrow(ArgumentError);
+        expect(() => parsePageArg(-1, 1)).toThrow(ArgumentError);
+        expect(() => parsePageArg('abc', 1)).toThrow(ArgumentError);
+    });
+});
+
+describe('coupang utils — product id validation', () => {
+    it('extracts numeric ids from ids and URLs', () => {
+        expect(requireProductIdArg('123456789')).toBe('123456789');
+        expect(requireProductIdArg('https://www.coupang.com/vp/products/123456789?itemId=1', '--url')).toBe('123456789');
+    });
+
+    it('rejects malformed product ids instead of building fake URLs', () => {
+        expect(() => requireProductIdArg('abc')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('abc 123456789')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://www.coupang.com/not-a-product', '--url')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://www.coupang.com/not-a-product/123456789', '--url')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://notcoupang.com/vp/products/123456789', '--url')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://example.com/vp/products/123456789', '--url')).toThrow(ArgumentError);
+    });
+});
+
+describe('coupang adapter registry shape', () => {
+    it('search has product_id column for round-trip into product', () => {
+        const search = getRegistry().get('coupang/search');
+        expect(search).toBeDefined();
+        expect(search.access).toBe('read');
+        expect(search.columns).toContain('product_id');
+        // Listing pairs with detail: id-shaped column present.
+        const idShaped = search.columns.find((c) => /_id$|^id$/.test(c));
+        expect(idShaped).toBe('product_id');
+    });
+
+    it('product cmd is a registered read adapter that pairs with search', () => {
+        const product = getRegistry().get('coupang/product');
+        expect(product).toBeDefined();
+        expect(product.access).toBe('read');
+        expect(product.columns).toContain('product_id');
+        expect(product.columns).toContain('title');
+        expect(product.columns).toContain('price');
+        expect(product.columns).toContain('seller');
+        expect(product.columns).toContain('rating');
+    });
+
+    it('add-to-cart remains write-class', () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        expect(cart).toBeDefined();
+        expect(cart.access).toBe('write');
+    });
+});
+
+describe('coupang search — typed errors (no silent fallback)', () => {
+    it('rejects empty query with ArgumentError', async () => {
+        const search = getRegistry().get('coupang/search');
+        // page object is irrelevant — we expect to fail before any browser call.
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: '   ' })).rejects.toThrow(ArgumentError);
+        await expect(search.func(fakePage, { query: '' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects unsupported --filter with ArgumentError', async () => {
+        const search = getRegistry().get('coupang/search');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: 'mouse', filter: 'eco' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects out-of-range --limit with ArgumentError (no silent clamp to 50)', async () => {
+        const search = getRegistry().get('coupang/search');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: 'mouse', limit: 999 })).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects out-of-range --page with ArgumentError', async () => {
+        const search = getRegistry().get('coupang/search');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: 'mouse', page: 0 })).rejects.toThrow(ArgumentError);
+    });
+});
+
+describe('coupang product — typed errors', () => {
+    it('rejects missing --product-id and --url with ArgumentError', async () => {
+        const product = getRegistry().get('coupang/product');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(product.func(fakePage, {})).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects malformed product id before navigation', async () => {
+        const product = getRegistry().get('coupang/product');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(product.func(fakePage, { 'product-id': 'abc' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('wraps browser failures as CommandExecutionError', async () => {
+        const product = getRegistry().get('coupang/product');
+        const fakePage = { goto: () => Promise.reject(new Error('browser down')) };
+        await expect(product.func(fakePage, { 'product-id': '123456789' })).rejects.toThrow(CommandExecutionError);
+    });
+});
+
+describe('coupang add-to-cart — typed errors', () => {
+    it('rejects missing --product-id and --url with ArgumentError', async () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(cart.func(fakePage, {})).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects malformed product id before navigation', async () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(cart.func(fakePage, { 'product-id': 'abc' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('wraps browser failures as CommandExecutionError', async () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        const fakePage = { goto: () => Promise.reject(new Error('browser down')) };
+        await expect(cart.func(fakePage, { 'product-id': '123456789' })).rejects.toThrow(CommandExecutionError);
+    });
+});