@zenalexa/unicli 0.218.1 → 0.220.0

package/src/adapters/coupang/product.ts

@@ -0,0 +1,256 @@
+/**
+ * @owner   src/adapters/coupang/product.ts
+ * @does    Register agent-facing Coupang product detail extraction implemented with site-specific safety checks.
+ * @needs   Coupang product page DOM and optional logged-in browser session for restricted products.
+ * @feeds   surface coverage ledger and Coupang search-to-detail workflows.
+ * @breaks  Coupang product page redirects, anti-bot pages, or product DOM/bootstrap schema drift can hide detail fields.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+import { js, str } from "../_shared/browser-tools.js";
+
+const COUPANG_ORIGIN = "https://www.coupang.com";
+const PRODUCT_ID_RE = /^\d{6,}$/;
+
+interface CoupangProductData {
+  product_id?: unknown;
+  title?: unknown;
+  price?: unknown;
+  original_price?: unknown;
+  discount_rate?: unknown;
+  rating?: unknown;
+  review_count?: unknown;
+  seller?: unknown;
+  brand?: unknown;
+  rocket?: unknown;
+  delivery_promise?: unknown;
+  image_url?: unknown;
+}
+
+interface CoupangProductResult {
+  ok?: unknown;
+  reason?: unknown;
+  currentProductId?: unknown;
+  loginHints?: { hasLoginLink?: unknown; hasMyCoupang?: unknown };
+  data?: CoupangProductData;
+}
+
+export function normalizeCoupangProductId(value: unknown): string {
+  const raw = str(value).trim();
+  const match = raw.match(/(?:^|\/vp\/products\/)(\d{6,})(?:[/?#]|$)/);
+  return match?.[1] ?? (PRODUCT_ID_RE.test(raw) ? raw : "");
+}
+
+export function requireCoupangProductId(value: unknown, label: string): string {
+  const raw = str(value).trim();
+  let id = "";
+  if (label === "url") {
+    let url: URL;
+    try {
+      url = new URL(raw.startsWith("http") ? raw : `${COUPANG_ORIGIN}${raw}`);
+    } catch {
+      throw new Error(
+        "Coupang url must be a product URL containing /vp/products/<id>.",
+      );
+    }
+    const host = url.hostname.toLowerCase();
+    const match = url.pathname.match(/^\/vp\/products\/(\d{6,})(?:\/|$)/);
+    if ((host === "coupang.com" || host.endsWith(".coupang.com")) && match)
+      id = match[1];
+  } else {
+    id = normalizeCoupangProductId(raw);
+  }
+  if (!id)
+    throw new Error(
+      `Coupang ${label} must be a numeric product ID or product URL.`,
+    );
+  return id;
+}
+
+export function canonicalizeCoupangProductUrl(
+  value: unknown,
+  productId: string,
+): string {
+  const raw = str(value).trim();
+  if (raw) {
+    try {
+      const url = new URL(
+        raw.startsWith("http") ? raw : `${COUPANG_ORIGIN}${raw}`,
+      );
+      const host = url.hostname.toLowerCase();
+      if (host !== "coupang.com" && !host.endsWith(".coupang.com")) return "";
+      const id =
+        normalizeCoupangProductId(url.pathname) ||
+        normalizeCoupangProductId(productId);
+      return id ? `${COUPANG_ORIGIN}/vp/products/${id}` : url.toString();
+    } catch {
+      return "";
+    }
+  }
+  return productId ? `${COUPANG_ORIGIN}/vp/products/${productId}` : "";
+}
+
+function numberOrNull(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const text = str(value).replace(/[^\d.]/g, "");
+  if (!text) return null;
+  const n = Number(text);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function mapCoupangProductRow(
+  productId: string,
+  data: CoupangProductData,
+  url: string,
+): Record<string, unknown> {
+  const actualId = normalizeCoupangProductId(data.product_id) || productId;
+  return {
+    product_id: actualId,
+    title: str(data.title).trim() || null,
+    price: numberOrNull(data.price),
+    original_price: numberOrNull(data.original_price),
+    discount_rate: numberOrNull(data.discount_rate),
+    rating: numberOrNull(data.rating),
+    review_count: numberOrNull(data.review_count),
+    seller: str(data.seller).trim() || null,
+    brand: str(data.brand).trim() || null,
+    rocket: str(data.rocket).trim() || null,
+    delivery_promise: str(data.delivery_promise).trim() || null,
+    image_url: str(data.image_url).trim() || null,
+    url: canonicalizeCoupangProductUrl("", actualId) || url,
+  };
+}
+
+function buildProductEvaluate(expectedProductId: string): string {
+  return `(() => {
+    const expectedProductId = ${js(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 };
+    }
+    const jsonLd = (() => {
+      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 types = Array.isArray(doc['@type']) ? doc['@type'] : [doc['@type']];
+            if (!types.some((type) => /Product/i.test(String(type || '')))) continue;
+            const offer = 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(offer?.price),
+              rating: parseNum(doc.aggregateRating?.ratingValue),
+              review_count: parseNum(doc.aggregateRating?.reviewCount),
+              seller: normalizeText(offer?.seller?.name),
+            };
+          }
+        } catch {}
+      }
+      return null;
+    })();
+    const dom = (() => {
+      const title = document.querySelector('.prod-buy-header__title, h1[class*="prod-buy-header"], h1[class*="ProductName"], h1[class*="product-name"]');
+      const price = document.querySelector('.total-price strong, .prod-sale-price strong, [class*="finalPrice"], [class*="sellingPrice"], [class*="price-value"]');
+      const original = document.querySelector('.origin-price, .base-price, del[class*="origin"], del[class*="base"], [class*="strike"], [class*="origin-price"]');
+      const discount = document.querySelector('.discount-percentage, [class*="discount"][class*="percent"], [class*="discountRate"]');
+      const rating = document.querySelector('.rating-star-num, [class*="ratingStar"], [class*="rating-star"], [class*="rating-num"], [class*="ProductRating"]');
+      const reviews = document.querySelector('.count, .rating-total-count, [class*="reviewCount"], [class*="review-count"]');
+      const seller = document.querySelector('.prod-sale-vendor-name, [class*="vendor-name"], [class*="vendorName"], [class*="sellerName"]');
+      const image = document.querySelector('.prod-image__detail, [class*="prod-image"] img, [class*="ProductImage"] img');
+      return {
+        title: normalizeText(title?.textContent),
+        price: parseNum(price?.textContent),
+        original_price: parseNum(original?.textContent),
+        discount_rate: parseNum(discount?.textContent),
+        rating: parseNum(rating?.getAttribute?.('aria-label') || rating?.textContent),
+        review_count: parseNum(reviews?.textContent),
+        seller: normalizeText(seller?.textContent),
+        image_url: normalizeText(image?.getAttribute?.('src') || image?.getAttribute?.('data-src')),
+      };
+    })();
+    const data = { ...(jsonLd || {}) };
+    for (const [key, value] of Object.entries(dom)) {
+      if (data[key] == null || data[key] === '') data[key] = value;
+    }
+    if (!data.title && data.price == null) {
+      return { ok: false, reason: 'NO_DATA_EXTRACTED', currentProductId, loginHints };
+    }
+    return { ok: true, currentProductId, loginHints, data };
+  })()`;
+}
+
+cli({
+  site: "coupang",
+  name: "product",
+  description: "Read full product detail for a Coupang product",
+  domain: "www.coupang.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: "product-id", type: "str", required: false, positional: true },
+    { name: "url", type: "str", required: false },
+  ],
+  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 Error("Either product-id or url is required.");
+    const productId = rawProductId
+      ? requireCoupangProductId(rawProductId, "product-id")
+      : requireCoupangProductId(kwargs.url, "url");
+    const url =
+      canonicalizeCoupangProductUrl(kwargs.url, productId) ||
+      canonicalizeCoupangProductUrl("", productId);
+    const p = page as IPage;
+    await p.goto(url, { waitUntil: "load", settleMs: 3000 });
+    await p.wait(2);
+    const result = (await p.evaluate(
+      buildProductEvaluate(productId),
+    )) as CoupangProductResult;
+    const loginHints = result?.loginHints ?? {};
+    if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
+      throw new Error("Coupang login is required.");
+    }
+    if (result?.reason === "PRODUCT_MISMATCH") {
+      throw new Error(
+        `Coupang product page redirected away from expected product ${productId}.`,
+      );
+    }
+    if (!result?.ok || !result.data) {
+      throw new Error(`No Coupang product data extracted from ${url}.`);
+    }
+    return [mapCoupangProductRow(productId, result.data, url)];
+  },
+});

package/src/adapters/coupang/search.yaml

@@ -3,6 +3,7 @@ name: search
 description: Search Coupang products
 domain: www.coupang.com
 strategy: intercept
+lint_listing_detail: skip
 browser: true
 
 args:

package/src/adapters/crates/registry.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapCratesDetailRow,
+  mapCratesSearchRows,
+  requireRegistryLimit,
+  requireRegistryString,
+} from "./registry.js";
+
+describe("crates agent-facing registry commands", () => {
+  it("validates shared registry args", () => {
+    expect(requireRegistryString(" serde ", "query")).toBe("serde");
+    expect(() => requireRegistryString("", "query")).toThrow(
+      "query is required",
+    );
+    expect(requireRegistryLimit(undefined, 20)).toBe(20);
+    expect(requireRegistryLimit("3", 20)).toBe(3);
+    expect(() => requireRegistryLimit("0", 20)).toThrow(
+      "limit must be an integer",
+    );
+    expect(() => requireRegistryLimit("101", 20)).toThrow(
+      "limit must be an integer",
+    );
+  });
+
+  it("maps crates.io search rows to agent-facing columns", () => {
+    expect(
+      mapCratesSearchRows(
+        [
+          {
+            name: "serde",
+            newest_version: "1.0.0",
+            description: "Serialize",
+            downloads: 10,
+            recent_downloads: 2,
+            repository: "https://github.com/serde-rs/serde",
+            updated_at: "2026-05-01T00:00:00Z",
+          },
+        ],
+        20,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        name: "serde",
+        latestVersion: "1.0.0",
+        description: "Serialize",
+        downloads: 10,
+        recentDownloads: 2,
+        repository: "https://github.com/serde-rs/serde",
+        updated: "2026-05-01",
+        url: "https://crates.io/crates/serde",
+      },
+    ]);
+  });
+
+  it("maps crates.io detail rows without sentinel output", () => {
+    expect(
+      mapCratesDetailRow({
+        crate: {
+          name: "tokio",
+          newest_version: "1.2.3",
+          description: "Runtime",
+          downloads: 100,
+          recent_downloads: 9,
+          num_versions: 42,
+          homepage: "https://tokio.rs",
+          documentation: "https://docs.rs/tokio",
+          repository: "https://github.com/tokio-rs/tokio",
+          created_at: "2020-01-01T00:00:00Z",
+          updated_at: "2026-05-02T00:00:00Z",
+        },
+        versions: [{ num: "1.2.3", license: "MIT" }],
+        keywords: [{ keyword: "async" }],
+        categories: [{ category: "asynchronous" }],
+      }),
+    ).toMatchObject({
+      name: "tokio",
+      latestVersion: "1.2.3",
+      license: "MIT",
+      keywords: "async",
+      categories: "asynchronous",
+      created: "2020-01-01",
+      updated: "2026-05-02",
+    });
+    expect(() => mapCratesDetailRow({})).toThrow(
+      "crates.io returned no crate metadata",
+    );
+  });
+});

package/src/adapters/crates/registry.ts

@@ -0,0 +1,247 @@
+/**
+ * @owner   src/adapters/crates/registry.ts
+ * @does    Register agent-facing crates.io search and crate metadata commands.
+ * @needs   Public crates.io API, TypeScript adapter loader, bounded argument parsing.
+ * @feeds   surface coverage ledger, package registry command surface, agent-readable registry rows.
+ * @breaks  crates.io API envelope drift, weak query validation, or silent empty results hide registry lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const CRATES_BASE = "https://crates.io";
+
+interface CratesSearchItem {
+  id?: unknown;
+  name?: unknown;
+  newest_version?: unknown;
+  max_stable_version?: unknown;
+  max_version?: unknown;
+  description?: unknown;
+  downloads?: unknown;
+  recent_downloads?: unknown;
+  repository?: unknown;
+  homepage?: unknown;
+  updated_at?: unknown;
+}
+
+interface CratesDetailBody {
+  crate?: CratesSearchItem & {
+    num_versions?: unknown;
+    created_at?: unknown;
+  };
+  versions?: Array<{
+    num?: unknown;
+    license?: unknown;
+  }>;
+  keywords?: Array<{
+    keyword?: unknown;
+    id?: unknown;
+  }>;
+  categories?: Array<{
+    category?: unknown;
+    slug?: unknown;
+  }>;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function requireRegistryString(value: unknown, name: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`${name} is required.`);
+  return text;
+}
+
+export function requireRegistryLimit(value: unknown, fallback: number): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 100) {
+    throw new Error(
+      `limit must be an integer in [1, 100]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+async function fetchCratesJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`crates.io request failed: HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+export function mapCratesSearchRows(
+  items: CratesSearchItem[],
+  limit: number,
+): Array<Record<string, unknown>> {
+  return items.slice(0, limit).map((crate, index) => {
+    const name = stringField(crate.name) || stringField(crate.id);
+    return {
+      rank: index + 1,
+      name,
+      latestVersion:
+        stringField(crate.newest_version) ||
+        stringField(crate.max_stable_version) ||
+        stringField(crate.max_version),
+      description: stringField(crate.description).trim(),
+      downloads: numberField(crate.downloads),
+      recentDownloads: numberField(crate.recent_downloads),
+      repository: stringField(crate.repository) || stringField(crate.homepage),
+      updated: stringField(crate.updated_at).slice(0, 10),
+      url: name ? `${CRATES_BASE}/crates/${name}` : "",
+    };
+  });
+}
+
+export function mapCratesDetailRow(
+  body: CratesDetailBody,
+): Record<string, unknown> {
+  const crate = body.crate;
+  if (!crate || !(stringField(crate.name) || stringField(crate.id))) {
+    throw new Error("crates.io returned no crate metadata.");
+  }
+  const versions = Array.isArray(body.versions) ? body.versions : [];
+  const latestVersion =
+    stringField(crate.newest_version) ||
+    stringField(crate.max_stable_version) ||
+    stringField(crate.max_version);
+  const latestRow =
+    versions.find((version) => stringField(version.num) === latestVersion) ??
+    versions[0] ??
+    {};
+  const name = stringField(crate.name) || stringField(crate.id);
+  const keywords = Array.isArray(body.keywords)
+    ? body.keywords
+        .map((item) => stringField(item.keyword) || stringField(item.id))
+        .filter(Boolean)
+        .join(", ")
+    : "";
+  const categories = Array.isArray(body.categories)
+    ? body.categories
+        .map((item) => stringField(item.category) || stringField(item.slug))
+        .filter(Boolean)
+        .join(", ")
+    : "";
+
+  return {
+    name,
+    latestVersion,
+    description: stringField(crate.description).trim(),
+    downloads: numberField(crate.downloads),
+    recentDownloads: numberField(crate.recent_downloads),
+    versions: numberField(crate.num_versions) ?? versions.length,
+    license: stringField(latestRow.license),
+    homepage: stringField(crate.homepage),
+    documentation: stringField(
+      (crate as { documentation?: unknown }).documentation,
+    ),
+    repository: stringField(crate.repository),
+    keywords,
+    categories,
+    created: stringField(crate.created_at).slice(0, 10),
+    updated: stringField(crate.updated_at).slice(0, 10),
+    url: `${CRATES_BASE}/crates/${name}`,
+  };
+}
+
+cli({
+  site: "crates",
+  name: "search",
+  description: "Search the public crates.io registry by keyword",
+  domain: "crates.io",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Search keyword",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Max results",
+    },
+  ],
+  columns: [
+    "rank",
+    "name",
+    "latestVersion",
+    "description",
+    "downloads",
+    "recentDownloads",
+    "repository",
+    "updated",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const query = requireRegistryString(kwargs.query, "query");
+    const limit = requireRegistryLimit(kwargs.limit, 20);
+    const url = `${CRATES_BASE}/api/v1/crates?q=${encodeURIComponent(query)}&per_page=${limit}`;
+    const body = (await fetchCratesJson(url)) as {
+      crates?: CratesSearchItem[];
+    };
+    const rows = mapCratesSearchRows(
+      Array.isArray(body.crates) ? body.crates : [],
+      limit,
+    );
+    if (rows.length === 0) {
+      throw new Error(`No crates.io results matched "${query}".`);
+    }
+    return rows;
+  },
+});
+
+cli({
+  site: "crates",
+  name: "crate",
+  description: "Single crates.io crate metadata",
+  domain: "crates.io",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "name",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "crates.io crate name",
+    },
+  ],
+  columns: [
+    "name",
+    "latestVersion",
+    "description",
+    "downloads",
+    "recentDownloads",
+    "versions",
+    "license",
+    "homepage",
+    "documentation",
+    "repository",
+    "keywords",
+    "categories",
+    "created",
+    "updated",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const name = requireRegistryString(kwargs.name, "name");
+    const body = (await fetchCratesJson(
+      `${CRATES_BASE}/api/v1/crates/${encodeURIComponent(name)}`,
+    )) as CratesDetailBody;
+    return [mapCratesDetailRow(body)];
+  },
+});