@jackwener/opencli 1.7.11 → 1.7.13

package/clis/coupang/product.js

@@ -0,0 +1,257 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { canonicalizeProductUrl, normalizeProductId, requireProductIdArg } from './utils.js';
+
+function escapeJsString(value) {
+    return JSON.stringify(value);
+}
+
+/**
+ * Build the in-page extractor for a Coupang product detail page.
+ *
+ * Tries three sources in order, mirroring search.js's chain:
+ *  1. JSON-LD <script type="application/ld+json"> (Product schema, most stable)
+ *  2. window.__INITIAL_STATE__ / __NEXT_DATA__ / similar globals (rich)
+ *  3. DOM scrape (fallback when bootstrap state is server-side only)
+ *
+ * Returns either a partial product object or a structured failure
+ * `{ loginHints, ok: false, reason }` so the caller can map it to typed errors.
+ *
+ * Design note (no-silent-empty): empty strings / null fields here MUST mean
+ * "upstream did not provide this field" — they should not be conflated with
+ * "extraction failed". A failed extraction returns ok=false so the caller can
+ * surface AuthRequiredError or EmptyResultError; partial success returns the
+ * fields it found and the caller decides whether to treat the partial row as
+ * usable.
+ */
+function buildProductDetailEvaluate(expectedProductId) {
+    return `
+    (async () => {
+      const expectedProductId = ${escapeJsString(expectedProductId)};
+      const normalizeText = (value) => (value == null ? '' : String(value).trim());
+      const parseNum = (value) => {
+        const text = normalizeText(value).replace(/[^\\d.]/g, '');
+        if (!text) return null;
+        const num = Number(text);
+        return Number.isFinite(num) ? num : null;
+      };
+
+      const loginHints = {
+        hasLoginLink: Boolean(document.querySelector('a[href*="login"], a[title*="로그인"]')),
+        hasMyCoupang: /마이쿠팡/.test(document.body.innerText || ''),
+      };
+
+      const pathMatch = location.pathname.match(/\\/vp\\/products\\/(\\d+)/);
+      const currentProductId = pathMatch?.[1] || '';
+      if (expectedProductId && currentProductId && expectedProductId !== currentProductId) {
+        return { ok: false, reason: 'PRODUCT_MISMATCH', currentProductId, loginHints };
+      }
+
+      // ── Source 1: JSON-LD Product schema ─────────────────────────────
+      const fromJsonLd = (() => {
+        const scripts = Array.from(document.querySelectorAll('script[type="application/ld+json"]'));
+        for (const script of scripts) {
+          try {
+            const docs = JSON.parse(script.textContent || 'null');
+            const items = Array.isArray(docs) ? docs : [docs];
+            for (const doc of items) {
+              if (!doc || typeof doc !== 'object') continue;
+              const t = doc['@type'];
+              const types = Array.isArray(t) ? t : [t];
+              if (!types.some((x) => /Product/i.test(String(x || '')))) continue;
+              const offers = Array.isArray(doc.offers) ? doc.offers[0] : doc.offers;
+              return {
+                title: normalizeText(doc.name),
+                brand: normalizeText(doc.brand?.name || doc.brand),
+                image_url: normalizeText(Array.isArray(doc.image) ? doc.image[0] : doc.image),
+                price: parseNum(offers?.price),
+                rating: parseNum(doc.aggregateRating?.ratingValue),
+                review_count: parseNum(doc.aggregateRating?.reviewCount),
+                seller: normalizeText(offers?.seller?.name),
+              };
+            }
+          } catch { /* malformed ld+json — skip and try next source */ }
+        }
+        return null;
+      })();
+
+      // ── Source 2: bootstrap globals (deeply nested vendorItem etc.) ──
+      const fromBootstrap = (() => {
+        const collect = (root) => {
+          if (!root || typeof root !== 'object') return null;
+          const queue = [root];
+          let depth = 0;
+          while (queue.length && depth < 5000) {
+            const node = queue.shift();
+            depth++;
+            if (!node || typeof node !== 'object') continue;
+            // A product-like leaf usually has both productId and salePrice / finalPrice / itemName.
+            const idCandidate = node.productId || node.product_id || node.id;
+            const titleCandidate = node.itemName || node.productName || node.name;
+            const priceCandidate = node.salePrice ?? node.finalPrice ?? node.sellingPrice ?? node.price;
+            if (idCandidate && titleCandidate && priceCandidate != null && /\\d{6,}/.test(String(idCandidate))) {
+              return {
+                product_id: String(idCandidate),
+                title: normalizeText(titleCandidate),
+                price: parseNum(priceCandidate),
+                original_price: parseNum(node.originalPrice ?? node.basePrice ?? node.listPrice),
+                discount_rate: parseNum(node.discountRate ?? node.discountPercent),
+                rating: parseNum(node.ratingAverage ?? node.rating ?? node.reviewRating),
+                review_count: parseNum(node.reviewCount ?? node.reviewsCount ?? node.ratingCount),
+                seller: normalizeText(node.vendorName ?? node.sellerName ?? node.merchantName),
+                brand: normalizeText(node.brandName ?? node.brand),
+                rocket: normalizeText(node.rocketType ?? node.deliveryBadgeType),
+                delivery_promise: normalizeText(node.deliveryPromise ?? node.arrivalText),
+              };
+            }
+            for (const value of Object.values(node)) {
+              if (value && typeof value === 'object') queue.push(value);
+            }
+          }
+          return null;
+        };
+        const candidates = [
+          window.__INITIAL_STATE__,
+          window.__NEXT_DATA__,
+          window.__APOLLO_STATE__,
+          window.__PRELOADED_STATE__,
+        ];
+        for (const c of candidates) {
+          const found = collect(c);
+          if (found) return found;
+        }
+        return null;
+      })();
+
+      // ── Source 3: DOM fallback ───────────────────────────────────────
+      const fromDom = (() => {
+        const titleNode = document.querySelector(
+          '.prod-buy-header__title, h1.prod-buy-header__title, h1[class*="prod-buy-header"], h2.prod-buy-header__title, h1[class*="ProductName"], h1[class*="product-name"]'
+        );
+        const priceNode = document.querySelector(
+          '.total-price strong, .prod-sale-price strong, [class*="finalPrice"], [class*="sellingPrice"], [class*="price-value"]'
+        );
+        const originalPriceNode = document.querySelector(
+          '.origin-price, .base-price, del[class*="origin"], del[class*="base"], [class*="strike"], [class*="origin-price"]'
+        );
+        const discountNode = document.querySelector(
+          '.discount-percentage, [class*="discount"][class*="percent"], [class*="discountRate"]'
+        );
+        const ratingNode = document.querySelector(
+          '.rating-star-num, [class*="ratingStar"], [class*="rating-star"], [class*="rating-num"], [class*="ProductRating"]'
+        );
+        const reviewCountNode = document.querySelector(
+          '.count, .rating-total-count, [class*="reviewCount"], [class*="review-count"]'
+        );
+        const sellerNode = document.querySelector(
+          '.prod-sale-vendor-name, [class*="vendor-name"], [class*="vendorName"], [class*="sellerName"]'
+        );
+        const imageNode = document.querySelector(
+          '.prod-image__detail, [class*="prod-image"] img, [class*="ProductImage"] img'
+        );
+        return {
+          title: normalizeText(titleNode?.textContent),
+          price: parseNum(priceNode?.textContent),
+          original_price: parseNum(originalPriceNode?.textContent),
+          discount_rate: parseNum(discountNode?.textContent),
+          rating: parseNum(ratingNode?.getAttribute?.('aria-label') || ratingNode?.textContent),
+          review_count: parseNum(reviewCountNode?.textContent),
+          seller: normalizeText(sellerNode?.textContent),
+          image_url: normalizeText(imageNode?.getAttribute?.('src') || imageNode?.getAttribute?.('data-src')),
+        };
+      })();
+
+      // Merge with priority: bootstrap > jsonld > dom (bootstrap is freshest /
+      // closest to the API; jsonld is well-typed; dom is last-resort).
+      const merge = (a, b) => {
+        if (!a) return b;
+        if (!b) return a;
+        const out = { ...a };
+        for (const [k, v] of Object.entries(b)) {
+          if (out[k] == null || out[k] === '') out[k] = v;
+        }
+        return out;
+      };
+      const merged = merge(merge(fromBootstrap, fromJsonLd), fromDom);
+      const hasAnyField = merged && (merged.title || merged.price != null);
+      if (!hasAnyField) {
+        return { ok: false, reason: 'NO_DATA_EXTRACTED', currentProductId, loginHints };
+      }
+
+      return {
+        ok: true,
+        currentProductId,
+        loginHints,
+        data: merged,
+      };
+    })()
+  `;
+}
+
+cli({
+    site: 'coupang',
+    name: 'product',
+    access: 'read',
+    description: 'Read full product detail (price, rating, seller, delivery) for a Coupang product',
+    domain: 'www.coupang.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'product-id', positional: true, required: false, help: 'Coupang product ID (digits only)' },
+        { name: 'url', required: false, help: 'Canonical Coupang product URL (alternative to --product-id)' },
+    ],
+    columns: [
+        'product_id', 'title', 'price', 'original_price', 'discount_rate',
+        'rating', 'review_count', 'seller', 'brand', 'rocket',
+        'delivery_promise', 'image_url', 'url',
+    ],
+    func: async (page, kwargs) => {
+        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).catch((error) => {
+            throw new CommandExecutionError(`coupang product navigation failed: ${error?.message || error}`);
+        });
+        await page.wait(2).catch((error) => {
+            throw new CommandExecutionError(`coupang product wait failed: ${error?.message || error}`);
+        });
+        const result = await page.evaluate(buildProductDetailEvaluate(productId)).catch((error) => {
+            throw new CommandExecutionError(`coupang product extraction failed: ${error?.message || error}`);
+        });
+        const loginHints = result?.loginHints ?? {};
+        if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
+            throw new AuthRequiredError('coupang.com', 'Please log into Coupang in Chrome and retry.');
+        }
+        if (result?.reason === 'PRODUCT_MISMATCH') {
+            const actualProductId = normalizeProductId(result?.currentProductId || '');
+            const observed = actualProductId ? `got ${actualProductId}` : 'no product id observed';
+            throw new EmptyResultError('coupang product', `Product page redirected: expected ${productId}, ${observed} (item may be sold out or unavailable in your region)`);
+        }
+        if (!result?.ok || !result?.data) {
+            throw new EmptyResultError('coupang product', `No product data extracted from ${finalUrl}. The page may have failed to render or this product is restricted.`);
+        }
+        const actualProductId = normalizeProductId(result?.currentProductId || result.data.product_id || productId);
+        const data = result.data;
+        return [{
+                product_id: actualProductId,
+                title: data.title || null,
+                price: data.price ?? null,
+                original_price: data.original_price ?? null,
+                discount_rate: data.discount_rate ?? null,
+                rating: data.rating ?? null,
+                review_count: data.review_count ?? null,
+                seller: data.seller || null,
+                brand: data.brand || null,
+                rocket: data.rocket || null,
+                delivery_promise: data.delivery_promise || null,
+                image_url: data.image_url || null,
+                url: canonicalizeProductUrl('', actualProductId) || finalUrl,
+            }];
+    },
+});

package/clis/coupang/search.js

@@ -1,5 +1,6 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { mergeSearchItems, normalizeSearchItem, sanitizeSearchItems } from './utils.js';
+import { mergeSearchItems, normalizeSearchItem, parseLimitArg, parsePageArg, sanitizeSearchItems } from './utils.js';
 function escapeJsString(value) {
     return JSON.stringify(value);
 }
@@ -399,6 +400,7 @@ function buildSearchEvaluate(query, limit, pageNumber) {
 cli({
     site: 'coupang',
     name: 'search',
+    access: 'read',
     description: 'Search Coupang products with logged-in browser session',
     domain: 'www.coupang.com',
     strategy: Strategy.COOKIE,
@@ -409,32 +411,50 @@ cli({
         { name: 'limit', type: 'int', default: 20, help: 'Max results (max 50)' },
         { name: 'filter', required: false, help: 'Optional search filter (currently supports: rocket)' },
     ],
-    columns: ['rank', 'title', 'price', 'unit_price', 'rating', 'review_count', 'rocket', 'delivery_type', 'delivery_promise', 'url'],
+    columns: ['rank', 'product_id', 'title', 'price', 'unit_price', 'rating', 'review_count', 'rocket', 'delivery_type', 'delivery_promise', 'url'],
     func: async (page, kwargs) => {
         const query = String(kwargs.query || '').trim();
-        const pageNumber = Math.max(Number(kwargs.page || 1), 1);
-        const limit = Math.min(Math.max(Number(kwargs.limit || 20), 1), 50);
+        if (!query) {
+            throw new ArgumentError('query cannot be empty');
+        }
+        const pageNumber = parsePageArg(kwargs.page, 1);
+        const limit = parseLimitArg(kwargs.limit, 20, 50);
         const filter = String(kwargs.filter || '').trim().toLowerCase();
-        if (!query)
-            throw new Error('Query is required');
+        if (filter && filter !== 'rocket') {
+            throw new ArgumentError(`Unsupported --filter "${filter}" (supported: rocket)`);
+        }
         const initialPage = filter ? 1 : pageNumber;
         const url = `https://www.coupang.com/np/search?q=${encodeURIComponent(query)}&channel=user&page=${initialPage}`;
-        await page.goto(url);
+        await page.goto(url).catch((error) => {
+            throw new CommandExecutionError(`coupang search navigation failed: ${error?.message || error}`);
+        });
         if (filter) {
-            const filterResult = await page.evaluate(buildApplyFilterEvaluate(filter));
+            const filterResult = await page.evaluate(buildApplyFilterEvaluate(filter)).catch((error) => {
+                throw new CommandExecutionError(`coupang search filter evaluation failed: ${error?.message || error}`);
+            });
             if (!filterResult?.ok) {
-                throw new Error(`Unsupported or unavailable filter: ${filter}`);
+                throw new EmptyResultError('coupang search', `Filter "${filter}" was not available on the current page; try without --filter or wait for Coupang to render the filter bar.`);
             }
-            await page.wait(3);
+            await page.wait(3).catch((error) => {
+                throw new CommandExecutionError(`coupang search wait failed: ${error?.message || error}`);
+            });
             if (pageNumber > 1) {
-                const locationInfo = await page.evaluate(buildCurrentLocationEvaluate());
+                const locationInfo = await page.evaluate(buildCurrentLocationEvaluate()).catch((error) => {
+                    throw new CommandExecutionError(`coupang search location evaluation failed: ${error?.message || error}`);
+                });
                 const filteredUrl = new URL(locationInfo?.href || url);
                 filteredUrl.searchParams.set('page', String(pageNumber));
-                await page.goto(filteredUrl.toString());
+                await page.goto(filteredUrl.toString()).catch((error) => {
+                    throw new CommandExecutionError(`coupang search filtered navigation failed: ${error?.message || error}`);
+                });
             }
         }
-        await page.autoScroll({ times: filter ? 3 : 2, delayMs: 1500 });
-        const raw = await page.evaluate(buildSearchEvaluate(query, limit, pageNumber));
+        await page.autoScroll({ times: filter ? 3 : 2, delayMs: 1500 }).catch((error) => {
+            throw new CommandExecutionError(`coupang search scroll failed: ${error?.message || error}`);
+        });
+        const raw = await page.evaluate(buildSearchEvaluate(query, limit, pageNumber)).catch((error) => {
+            throw new CommandExecutionError(`coupang search extraction failed: ${error?.message || error}`);
+        });
         const loginHints = raw?.loginHints ?? {};
         const items = Array.isArray(raw?.items) ? raw.items : [];
         const domItems = Array.isArray(raw?.domItems) ? raw.domItems : [];
@@ -443,8 +463,11 @@ cli({
         const normalized = filter
             ? sanitizeSearchItems(normalizedDom, limit)
             : mergeSearchItems(normalizedBase, normalizedDom, limit);
-        if (!normalized.length && loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
-            throw new Error('Coupang login required. Please log into Coupang in Chrome and retry.');
+        if (!normalized.length) {
+            if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
+                throw new AuthRequiredError('coupang.com', 'Please log into Coupang in Chrome and retry.');
+            }
+            throw new EmptyResultError('coupang search', `No products matched "${query}". Try a more specific keyword or remove --filter.`);
         }
         return normalized;
     },

package/clis/coupang/utils.js

@@ -1,3 +1,36 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+/**
+ * Parse a positive integer arg (--limit / --page / --review-page).
+ *
+ * Throws ArgumentError on out-of-range / non-integer values rather than
+ * silently clamping. We prefer typed-fail-fast over silent clamping for the
+ * same reason as feedback_typed_fail_fast_for_adapters: callers cannot tell
+ * that their value was rewritten and end up confused why "limit=999" returned
+ * 50 rows.
+ */
+export function parseLimitArg(raw, fallback, max) {
+    if (raw === undefined || raw === null || raw === '') {
+        return fallback;
+    }
+    const num = Number(raw);
+    if (!Number.isInteger(num) || num < 1 || num > max) {
+        throw new ArgumentError(`--limit must be an integer between 1 and ${max} (got ${raw})`);
+    }
+    return num;
+}
+
+export function parsePageArg(raw, fallback) {
+    if (raw === undefined || raw === null || raw === '') {
+        return fallback;
+    }
+    const num = Number(raw);
+    if (!Number.isInteger(num) || num < 1) {
+        throw new ArgumentError(`--page must be a positive integer (got ${raw})`);
+    }
+    return num;
+}
+
 function itemKey(item) {
     return item.url || item.product_id || `${item.title}:${item.price ?? ''}`;
 }
@@ -61,7 +94,28 @@ export function normalizeProductId(raw) {
     if (!text)
         return '';
     const match = text.match(/\/vp\/products\/(\d+)/) || text.match(/\b(\d{6,})\b/);
-    return match?.[1] ?? text;
+    return match?.[1] ?? '';
+}
+export function requireProductIdArg(raw, label = '--product-id') {
+    const text = asString(raw);
+    if (label === '--url') {
+        try {
+            const url = new URL(text.startsWith('http') ? text : `https://www.coupang.com${text}`);
+            const match = url.pathname.match(/^\/vp\/products\/(\d{6,})(?:\/|$)/);
+            const isCoupangHost = url.hostname === 'coupang.com' || url.hostname.endsWith('.coupang.com');
+            if (isCoupangHost && match) {
+                return match[1];
+            }
+        }
+        catch {
+            // Fall through to the typed validation error below.
+        }
+        throw new ArgumentError(`${label} must be a Coupang product URL containing /vp/products/<id>`);
+    }
+    if (!/^\d{6,}$/.test(text)) {
+        throw new ArgumentError(`${label} must be a numeric Coupang product ID`);
+    }
+    return text;
 }
 export function canonicalizeProductUrl(rawUrl, productId) {
     const raw = asString(rawUrl);

package/clis/crates/crate.js

@@ -0,0 +1,62 @@
+// crates crate — fetch a single crate's metadata.
+//
+// Hits `https://crates.io/api/v1/crates/<name>`. Returns the agent-useful
+// projection: name, latest version, description, total + recent downloads,
+// homepage / docs / repo, license (from latest version row), version count,
+// created / updated timestamps.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { CRATES_BASE, cratesFetch, requireCrateName } from './utils.js';
+
+cli({
+    site: 'crates',
+    name: 'crate',
+    access: 'read',
+    description: 'Single crates.io crate metadata (latest version, downloads, license, repo)',
+    domain: 'crates.io',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'crates.io crate name (e.g. "serde", "tokio")' },
+    ],
+    columns: [
+        'name', 'latestVersion', 'description', 'downloads', 'recentDownloads', 'versions',
+        'license', 'homepage', 'documentation', 'repository', 'keywords', 'categories', 'created', 'updated', 'url',
+    ],
+    func: async (args) => {
+        const name = requireCrateName(args.name);
+        const body = await cratesFetch(`${CRATES_BASE}/api/v1/crates/${encodeURIComponent(name)}`, `crates crate ${name}`);
+        const c = body?.crate;
+        if (!c || !c.id) {
+            throw new EmptyResultError('crates crate', `crates.io returned no metadata for "${name}".`);
+        }
+        const versions = Array.isArray(body.versions) ? body.versions : [];
+        const latestRow = versions.find((v) => v.num === c.newest_version)
+            || versions.find((v) => v.num === c.max_stable_version)
+            || versions[0]
+            || {};
+        const keywords = Array.isArray(body.keywords)
+            ? body.keywords.map((k) => k?.keyword || k?.id || '').filter(Boolean).join(', ')
+            : '';
+        const categories = Array.isArray(body.categories)
+            ? body.categories.map((cat) => cat?.category || cat?.slug || '').filter(Boolean).join(', ')
+            : '';
+        return [{
+            name: String(c.name ?? c.id),
+            latestVersion: String(c.newest_version ?? c.max_stable_version ?? c.max_version ?? ''),
+            description: String(c.description ?? '').trim(),
+            downloads: c.downloads != null ? Number(c.downloads) : null,
+            recentDownloads: c.recent_downloads != null ? Number(c.recent_downloads) : null,
+            versions: c.num_versions != null ? Number(c.num_versions) : versions.length,
+            license: String(latestRow.license ?? ''),
+            homepage: String(c.homepage ?? ''),
+            documentation: String(c.documentation ?? ''),
+            repository: String(c.repository ?? ''),
+            keywords,
+            categories,
+            created: String(c.created_at ?? '').slice(0, 10),
+            updated: String(c.updated_at ?? '').slice(0, 10),
+            url: `https://crates.io/crates/${c.name ?? c.id}`,
+        }];
+    },
+});

package/clis/crates/search.js

@@ -0,0 +1,44 @@
+// crates search — search the crates.io registry by free-text query.
+//
+// Hits `https://crates.io/api/v1/crates?q=…&per_page=…`. Returns name (round-
+// trips into `crates crate`), latest version, description, downloads, recent
+// downloads, repository, last-update.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { CRATES_BASE, cratesFetch, requireBoundedInt, requireString } from './utils.js';
+
+cli({
+    site: 'crates',
+    name: 'search',
+    access: 'read',
+    description: 'Search the public crates.io registry by keyword',
+    domain: 'crates.io',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "serde", "async runtime")' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },
+    ],
+    columns: ['rank', 'name', 'latestVersion', 'description', 'downloads', 'recentDownloads', 'repository', 'updated', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 20, 100);
+        const url = `${CRATES_BASE}/api/v1/crates?q=${encodeURIComponent(query)}&per_page=${limit}`;
+        const body = await cratesFetch(url, 'crates search');
+        const list = Array.isArray(body?.crates) ? body.crates : [];
+        if (!list.length) {
+            throw new EmptyResultError('crates search', `No crates.io results matched "${query}".`);
+        }
+        return list.slice(0, limit).map((c, i) => ({
+            rank: i + 1,
+            name: String(c.name ?? c.id ?? ''),
+            latestVersion: String(c.newest_version ?? c.max_stable_version ?? c.max_version ?? ''),
+            description: String(c.description ?? '').trim(),
+            downloads: c.downloads != null ? Number(c.downloads) : null,
+            recentDownloads: c.recent_downloads != null ? Number(c.recent_downloads) : null,
+            repository: String(c.repository ?? c.homepage ?? ''),
+            updated: String(c.updated_at ?? '').slice(0, 10),
+            url: c.name ? `https://crates.io/crates/${c.name}` : '',
+        }));
+    },
+});

package/clis/crates/utils.js

@@ -0,0 +1,72 @@
+// Shared helpers for the crates.io adapters.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const CRATES_BASE = 'https://crates.io';
+const UA = 'opencli-crates-adapter (+https://github.com/jackwener/opencli)';
+
+// crates.io crate names: 1-64 chars, ascii letters/digits/-_, must start with a letter.
+const CRATE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`crates ${label} cannot be empty`);
+    return s;
+}
+
+export function requireCrateName(value) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError('crates crate name is required (e.g. "serde", "tokio")');
+    if (!CRATE_NAME.test(s)) {
+        throw new ArgumentError(
+            `crates crate name "${value}" is not a valid crates.io name`,
+            'Names start with an ASCII letter, then 0-63 chars of letters / digits / "_-".',
+        );
+    }
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`crates ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`crates ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export async function cratesFetch(url, label) {
+    let resp;
+    try {
+        // crates.io requires a descriptive User-Agent per https://crates.io/data-access
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that crates.io is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `crates.io returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'crates.io rate-limits unauthenticated traffic; wait a few seconds and retry.',
+        );
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}