@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/defillama/protocols.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapDefillamaDetailRow,
+  mapDefillamaProtocolRows,
+  requireDefillamaLimit,
+  requireDefillamaSlug,
+  unixToDate,
+} from "./protocols.js";
+
+describe("defillama agent-facing protocol commands", () => {
+  it("validates limits and slugs", () => {
+    expect(requireDefillamaLimit(undefined)).toBe(30);
+    expect(requireDefillamaLimit("500")).toBe(500);
+    expect(() => requireDefillamaLimit("501")).toThrow("defillama limit must");
+    expect(requireDefillamaSlug("aave-v3")).toBe("aave-v3");
+    expect(() => requireDefillamaSlug("../aave")).toThrow("not valid");
+  });
+
+  it("normalizes unix timestamps", () => {
+    expect(unixToDate(1)).toBe("1970-01-01");
+    expect(unixToDate(null)).toBeNull();
+  });
+
+  it("maps protocol list rows sorted by TVL", () => {
+    expect(
+      mapDefillamaProtocolRows(
+        [
+          { slug: "small", name: "Small", tvl: 1 },
+          {
+            slug: "large",
+            name: "Large",
+            category: "Lending",
+            tvl: "10",
+            chains: ["Ethereum"],
+          },
+        ],
+        2,
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        slug: "large",
+        name: "Large",
+        category: "Lending",
+        tvl: 10,
+        chains: "Ethereum",
+      },
+      { rank: 2, slug: "small", tvl: 1 },
+    ]);
+  });
+
+  it("maps protocol detail rows with list metadata", () => {
+    expect(
+      mapDefillamaDetailRow(
+        "aave",
+        {
+          name: "Aave",
+          tvl: [{ date: 1, totalLiquidityUSD: "100" }],
+          chains: ["Ethereum"],
+          github: ["aave/protocol-v2"],
+          twitter: "aave",
+          url: "https://aave.com",
+        },
+        [{ slug: "aave", category: "Lending", chains: ["Polygon"] }],
+      ),
+    ).toMatchObject({
+      slug: "aave",
+      name: "Aave",
+      category: "Lending",
+      tvl: 100,
+      chains: "Ethereum, Polygon",
+      github: "aave/protocol-v2",
+    });
+  });
+});

package/src/adapters/defillama/protocols.ts

@@ -0,0 +1,253 @@
+/**
+ * @owner   src/adapters/defillama/protocols.ts
+ * @does    Register agent-facing DefiLlama protocol list and detail commands.
+ * @needs   DefiLlama public API, bounded result limits, validated protocol slugs.
+ * @feeds   surface coverage ledger, DeFi protocol TVL rows, protocol metadata detail.
+ * @breaks  DefiLlama API drift, weak slug validation, or silent empty rows hide DeFi data failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://api.llama.fi";
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+
+export function requireDefillamaLimit(value: unknown): number {
+  const raw =
+    value === undefined || value === null || value === "" ? 30 : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+    throw new Error("defillama limit must be an integer in [1, 500].");
+  }
+  return limit;
+}
+
+export function requireDefillamaSlug(value: unknown): string {
+  const slug = String(value ?? "").trim();
+  if (!slug) throw new Error("defillama slug cannot be empty.");
+  if (!SLUG_RE.test(slug)) {
+    throw new Error(`defillama slug "${String(value)}" is not valid.`);
+  }
+  return slug;
+}
+
+export function unixToDate(value: unknown): string | null {
+  if (value == null) return null;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const date = new Date(n > 1e12 ? n : n * 1000);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10);
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function numberField(value: unknown): number | null {
+  const n =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim()
+        ? Number(value)
+        : NaN;
+  return Number.isFinite(n) ? n : null;
+}
+
+function joinStrings(value: unknown): string {
+  return Array.isArray(value)
+    ? value.filter((item) => typeof item === "string" && item.trim()).join(", ")
+    : "";
+}
+
+function objectField(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function mapDefillamaProtocolRows(
+  rows: Array<Record<string, unknown>>,
+  limit: number,
+): Array<Record<string, unknown>> {
+  return rows
+    .filter((row) => (row.slug || row.name) && numberField(row.tvl) != null)
+    .sort((a, b) => (numberField(b.tvl) ?? 0) - (numberField(a.tvl) ?? 0))
+    .slice(0, limit)
+    .map((row, index) => {
+      const slug = stringField(row.slug);
+      return {
+        rank: index + 1,
+        slug,
+        name: stringField(row.name),
+        category: stringField(row.category),
+        tvl: numberField(row.tvl),
+        mcap: numberField(row.mcap),
+        change_1d: numberField(row.change_1d),
+        change_7d: numberField(row.change_7d),
+        chains: joinStrings(row.chains),
+        listedAt: unixToDate(row.listedAt),
+        url: slug ? `https://defillama.com/protocol/${slug}` : "",
+      };
+    });
+}
+
+export function mapDefillamaDetailRow(
+  slug: string,
+  detail: Record<string, unknown>,
+  protocols: Array<Record<string, unknown>>,
+): Record<string, unknown> {
+  const tvlSeries = Array.isArray(detail.tvl)
+    ? (detail.tvl as Array<Record<string, unknown>>)
+    : [];
+  const lastPoint = tvlSeries[tvlSeries.length - 1] ?? {};
+  const isParent = detail.isParentProtocol === true;
+  const chains = new Set(
+    Array.isArray(detail.chains) ? (detail.chains as Array<string>) : [],
+  );
+  let category = "";
+  if (isParent) {
+    for (const protocol of protocols) {
+      if (
+        protocol.parentProtocol === detail.id &&
+        Array.isArray(protocol.chains)
+      ) {
+        for (const chain of protocol.chains) {
+          if (typeof chain === "string") chains.add(chain);
+        }
+      }
+    }
+  } else {
+    const match = protocols.find((protocol) => protocol.slug === slug);
+    category = stringField(match?.category);
+    if (Array.isArray(match?.chains)) {
+      for (const chain of match.chains) {
+        if (typeof chain === "string") chains.add(chain);
+      }
+    }
+  }
+  return {
+    slug,
+    name: stringField(detail.name),
+    category,
+    isParent,
+    tvl: numberField(lastPoint.totalLiquidityUSD),
+    tvlAt: unixToDate(lastPoint.date),
+    mcap: numberField(detail.mcap),
+    chains: [...chains].join(", "),
+    twitter: stringField(detail.twitter),
+    github: joinStrings(detail.github),
+    audits: stringField(detail.audits),
+    listedAt: unixToDate(detail.listedAt),
+    description: stringField(detail.description),
+    website: stringField(detail.url),
+    url: `https://defillama.com/protocol/${slug}`,
+  };
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-defillama (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  });
+  if (response.status === 404) throw new Error(`${label} returned no result.`);
+  if (response.status === 400) throw new Error(`${label} returned HTTP 400.`);
+  if (response.status === 429) throw new Error(`${label} returned HTTP 429.`);
+  if (!response.ok)
+    throw new Error(`${label} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "defillama",
+  name: "protocols",
+  description: "Top DeFi protocols by current TVL",
+  domain: "defillama.com",
+  strategy: Strategy.PUBLIC,
+  args: [{ name: "limit", type: "int", default: 30, description: "Max rows" }],
+  columns: [
+    "rank",
+    "slug",
+    "name",
+    "category",
+    "tvl",
+    "mcap",
+    "change_1d",
+    "change_7d",
+    "chains",
+    "listedAt",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const limit = requireDefillamaLimit(kwargs.limit);
+    const body = await fetchJson(
+      `${API_BASE}/protocols`,
+      "defillama protocols",
+    );
+    const rows = mapDefillamaProtocolRows(
+      Array.isArray(body) ? (body as Array<Record<string, unknown>>) : [],
+      limit,
+    );
+    if (rows.length === 0)
+      throw new Error("defillama protocols returned no rows.");
+    return rows;
+  },
+});
+
+cli({
+  site: "defillama",
+  name: "protocol",
+  description: "Fetch DefiLlama protocol detail by slug",
+  domain: "defillama.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "slug",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Protocol slug",
+    },
+  ],
+  columns: [
+    "slug",
+    "name",
+    "category",
+    "isParent",
+    "tvl",
+    "tvlAt",
+    "mcap",
+    "chains",
+    "twitter",
+    "github",
+    "audits",
+    "listedAt",
+    "description",
+    "website",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const slug = requireDefillamaSlug(kwargs.slug);
+    const detail = objectField(
+      await fetchJson(
+        `${API_BASE}/protocol/${encodeURIComponent(slug)}`,
+        "defillama protocol",
+      ),
+    );
+    if (!detail.name)
+      throw new Error(`defillama protocol returned no row for "${slug}".`);
+    const protocols = await fetchJson(
+      `${API_BASE}/protocols`,
+      "defillama protocol list",
+    );
+    return [
+      mapDefillamaDetailRow(
+        slug,
+        detail,
+        Array.isArray(protocols)
+          ? (protocols as Array<Record<string, unknown>>)
+          : [],
+      ),
+    ];
+  },
+});

package/src/adapters/devto/read.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapDevtoArticleRow,
+  requireDevtoArticleId,
+  requireDevtoMaxLength,
+} from "./read.js";
+
+describe("devto agent-facing read command", () => {
+  it("validates ids and max-length", () => {
+    expect(requireDevtoArticleId(" 3605688 ")).toBe("3605688");
+    expect(() => requireDevtoArticleId("slug")).toThrow("Invalid DEV.to");
+    expect(requireDevtoMaxLength(undefined)).toBe(20_000);
+    expect(requireDevtoMaxLength("100")).toBe(100);
+    expect(() => requireDevtoMaxLength("99")).toThrow("max-length");
+  });
+
+  it("maps article body, tags, and explicit truncation", () => {
+    expect(
+      mapDevtoArticleRow(
+        {
+          id: 3605688,
+          title: "Readable",
+          body_markdown: `${"x".repeat(105)}`,
+          user: { username: "author" },
+          public_reactions_count: 7,
+          reading_time_minutes: 3,
+          tag_list: ["ai", "cli"],
+          published_at: "2026-05-12T00:00:00Z",
+          url: "https://dev.to/a/readable",
+        },
+        "3605688",
+        100,
+      ),
+    ).toEqual({
+      id: 3605688,
+      title: "Readable",
+      author: "author",
+      reactions: 7,
+      reading_time: 3,
+      tags: "ai, cli",
+      published_at: "2026-05-12T00:00:00Z",
+      body: `${"x".repeat(100)}\n\n... [truncated]`,
+      url: "https://dev.to/a/readable",
+    });
+    expect(() => mapDevtoArticleRow({ id: 1 }, "1", 100)).toThrow(
+      "body_markdown",
+    );
+  });
+});

package/src/adapters/devto/read.ts

@@ -0,0 +1,145 @@
+/**
+ * @owner   src/adapters/devto/read.ts
+ * @does    Register agent-facing DEV.to article reader.
+ * @needs   Public dev.to articles API, numeric article ids, explicit body truncation.
+ * @feeds   surface coverage ledger, developer article reading workflow.
+ * @breaks  DEV.to API shape drift or missing body_markdown would silently hide article content.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const DEVTO_ARTICLE_BASE = "https://dev.to/api/articles";
+
+interface DevtoArticle {
+  id?: unknown;
+  title?: unknown;
+  body_markdown?: unknown;
+  user?: { username?: unknown };
+  public_reactions_count?: unknown;
+  reading_time_minutes?: unknown;
+  tag_list?: unknown;
+  tags?: unknown;
+  published_at?: unknown;
+  url?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+export function requireDevtoArticleId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!/^\d+$/.test(id)) {
+    throw new Error(`Invalid DEV.to article id: ${String(value)}.`);
+  }
+  return id;
+}
+
+export function requireDevtoMaxLength(
+  value: unknown,
+  fallback = 20_000,
+): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 100) {
+    throw new Error("devto read max-length must be an integer >= 100.");
+  }
+  return n;
+}
+
+function normalizeTags(article: DevtoArticle): string {
+  const tags = article.tag_list ?? article.tags ?? "";
+  return Array.isArray(tags) ? tags.map(String).join(", ") : String(tags);
+}
+
+export function mapDevtoArticleRow(
+  article: DevtoArticle,
+  requestedId: string,
+  maxLength: number,
+): Record<string, unknown> {
+  if (!article || !article.id) {
+    throw new Error(`DEV.to article ${requestedId} returned no article.`);
+  }
+  const body = stringField(article.body_markdown);
+  if (!body.trim()) {
+    throw new Error(
+      `DEV.to article ${requestedId} did not include body_markdown.`,
+    );
+  }
+  return {
+    id: article.id,
+    title: stringField(article.title),
+    author: stringField(article.user?.username) || "[deleted]",
+    reactions: numberField(article.public_reactions_count),
+    reading_time: numberField(article.reading_time_minutes),
+    tags: normalizeTags(article),
+    published_at: stringField(article.published_at),
+    body:
+      body.length > maxLength
+        ? `${body.slice(0, maxLength)}\n\n... [truncated]`
+        : body,
+    url: stringField(article.url),
+  };
+}
+
+async function fetchDevtoArticle(id: string): Promise<DevtoArticle> {
+  const response = await fetch(`${DEVTO_ARTICLE_BASE}/${id}`, {
+    headers: {
+      "User-Agent": "unicli-devto/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (response.status === 404)
+    throw new Error(`DEV.to article ${id} not found.`);
+  if (!response.ok) {
+    throw new Error(
+      `DEV.to API returned HTTP ${response.status} for article ${id}.`,
+    );
+  }
+  return (await response.json()) as DevtoArticle;
+}
+
+cli({
+  site: "devto",
+  name: "read",
+  description: "Read a DEV.to article body by id",
+  domain: "dev.to",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "DEV.to numeric article id",
+    },
+    {
+      name: "max-length",
+      type: "int",
+      default: 20_000,
+      description: "Max body characters",
+    },
+  ],
+  columns: [
+    "id",
+    "title",
+    "author",
+    "reactions",
+    "reading_time",
+    "tags",
+    "published_at",
+    "body",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireDevtoArticleId(kwargs.id);
+    const maxLength = requireDevtoMaxLength(
+      kwargs["max-length"] ?? kwargs.maxLength,
+    );
+    return [mapDevtoArticleRow(await fetchDevtoArticle(id), id, maxLength)];
+  },
+});

package/src/adapters/dianping/shop.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import {
+  classifyDianpingShopFailure,
+  mapDianpingShopFields,
+  normalizeDianpingShopId,
+  parseDianpingPrice,
+  parseDianpingReviewCount,
+} from "./shop.js";
+
+function pageMock(evaluateResults: unknown[]) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(async () => evaluateResults.shift()),
+  };
+}
+
+describe("dianping shop agent-facing command", () => {
+  it("validates shop ids and parses Dianping numbers", () => {
+    expect(normalizeDianpingShopId("abc_123-DEF")).toBe("abc_123-DEF");
+    expect(
+      normalizeDianpingShopId("https://www.dianping.com/shop/abc_123?x=1"),
+    ).toBe("abc_123");
+    expect(() => normalizeDianpingShopId("")).toThrow("non-empty");
+    expect(() => normalizeDianpingShopId("bad/id")).toThrow("shop_id");
+    expect(parseDianpingReviewCount("1.2万条")).toBe(12000);
+    expect(parseDianpingReviewCount("21241条")).toBe(21241);
+    expect(parseDianpingReviewCount("")).toBeNull();
+    expect(parseDianpingPrice("人均￥109")).toBe(109);
+    expect(parseDianpingPrice("暂无")).toBeNull();
+  });
+
+  it("maps shop details to surface field rows", () => {
+    expect(
+      mapDianpingShopFields(
+        "abc_123",
+        {
+          name: " 芈重山老火锅 ",
+          rating: "4.8",
+          reviewsRaw: "1.2万条",
+          priceRaw: "人均￥109",
+          rank: "海淀区重庆火锅口味榜 · 第1名",
+          breakdown: { 口味: 4.8, 环境: "4.7", 服务: 4.6, 食材: 4.9 },
+          hours: "营业中 11:00-次日02:00",
+          address: "北京市海淀区",
+          subway: "距地铁五道口站步行300m",
+          features: ["可停车", "有包间"],
+          url: "https://www.dianping.com/shop/abc_123",
+        },
+        "https://www.dianping.com/shop/abc_123",
+      ),
+    ).toEqual([
+      { field: "shop_id", value: "abc_123" },
+      { field: "name", value: "芈重山老火锅" },
+      { field: "rating", value: 4.8 },
+      { field: "reviews", value: 12000 },
+      { field: "price", value: 109 },
+      { field: "rank", value: "海淀区重庆火锅口味榜 · 第1名" },
+      { field: "taste", value: 4.8 },
+      { field: "environment", value: 4.7 },
+      { field: "service", value: 4.6 },
+      { field: "ingredients", value: 4.9 },
+      { field: "hours", value: "营业中 11:00-次日02:00" },
+      { field: "address", value: "北京市海淀区" },
+      { field: "subway", value: "距地铁五道口站步行300m" },
+      { field: "features", value: "可停车, 有包间" },
+      { field: "url", value: "https://www.dianping.com/shop/abc_123" },
+    ]);
+  });
+
+  it("extracts Dianping shop details", async () => {
+    const command = resolveCommand("dianping", "shop")?.command;
+    const page = pageMock([
+      {
+        ok: true,
+        name: "芈重山老火锅",
+        rating: "4.8",
+        reviewsRaw: "21241条",
+        priceRaw: "￥109",
+        breakdown: { 口味: 4.8 },
+        url: "https://www.dianping.com/shop/abc_123",
+      },
+    ]);
+    await expect(command!.func!(page, { shop_id: "abc_123" })).resolves.toEqual(
+      expect.arrayContaining([
+        { field: "shop_id", value: "abc_123" },
+        { field: "name", value: "芈重山老火锅" },
+        { field: "rating", value: 4.8 },
+        { field: "reviews", value: 21241 },
+        { field: "price", value: 109 },
+        { field: "taste", value: 4.8 },
+      ]),
+    );
+    expect(page.goto).toHaveBeenCalledWith(
+      "https://www.dianping.com/shop/abc_123",
+      { waitUntil: "load", settleMs: 3000 },
+    );
+    expect(page.wait).toHaveBeenCalledWith(3);
+  });
+
+  it("fails before navigation on malformed shop ids", async () => {
+    const command = resolveCommand("dianping", "shop")?.command;
+    const page = pageMock([]);
+    await expect(command!.func!(page, { shop_id: "bad/id" })).rejects.toThrow(
+      "Dianping shop_id",
+    );
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it("classifies Dianping auth, captcha, and empty pages", () => {
+    expect(() =>
+      classifyDianpingShopFailure(
+        "美团安全验证 请依次点击",
+        "https://verify.meituan.com",
+        "abc",
+      ),
+    ).toThrow("blocked by captcha");
+    expect(() =>
+      classifyDianpingShopFailure(
+        "请先登录",
+        "https://login.dianping.com",
+        "abc",
+      ),
+    ).toThrow("requires login");
+    expect(() =>
+      classifyDianpingShopFailure(
+        "商户不存在",
+        "https://www.dianping.com/shop/abc",
+        "abc",
+      ),
+    ).toThrow("not found");
+  });
+});