@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/deepseek/web.ts

@@ -14,6 +14,8 @@ import {
 
 const HOME = "https://chat.deepseek.com";
 const CHAT = `${HOME}/`;
+const CONVERSATION_ID_RE =
+  /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
 const INPUT = "textarea, [contenteditable='true'], .chat-input textarea";
 const FILE_INPUT = 'input[type="file"]';
 const MESSAGES =
@@ -37,6 +39,13 @@ async function readConversation(
   page: IPage,
 ): Promise<Record<string, unknown>[]> {
   await openChat(page);
+  return readVisibleConversation(page, true);
+}
+
+async function readVisibleConversation(
+  page: IPage,
+  withFallback: boolean,
+): Promise<Record<string, unknown>[]> {
   const items = (await page.evaluate(`(() => {
     const nodes = [...document.querySelectorAll(${js(MESSAGES)})];
     const rows = nodes.map((node, index) => ({
@@ -44,11 +53,28 @@ async function readConversation(
       text: (node.textContent || '').trim(),
       role: /user|human|question/i.test(node.getAttribute('class') || '') ? 'user' : 'assistant'
     })).filter((row) => row.text.length > 0);
-    return rows.length ? rows : [{ index: 1, role: 'page', text: (document.body?.innerText || '').trim().slice(0, 4000) }];
+    return rows.length ? rows : (${withFallback} ? [{ index: 1, role: 'page', text: (document.body?.innerText || '').trim().slice(0, 4000) }] : []);
   })()`)) as Record<string, unknown>[];
   return items;
 }
 
+export function parseDeepSeekConversationId(value: unknown): string {
+  const raw = str(value).trim();
+  if (!raw) throw new Error("DeepSeek conversation ID cannot be empty.");
+  const urlMatch = raw.match(/\/a\/chat\/s\/([a-f0-9-]+)/i);
+  const candidate = urlMatch ? urlMatch[1] : raw;
+  if (!CONVERSATION_ID_RE.test(candidate)) {
+    throw new Error(
+      `Invalid DeepSeek conversation ID: ${raw}. Expected a UUID or /a/chat/s/<id> URL.`,
+    );
+  }
+  return candidate.toLowerCase();
+}
+
+function deepSeekConversationUrl(id: string): string {
+  return `${HOME}/a/chat/s/${id}`;
+}
+
 function resolveUploadFiles(value: unknown): string[] {
   const raw = str(value).trim();
   if (!raw) return [];
@@ -201,3 +227,54 @@ cli({
     return rows.slice(0, limit);
   },
 });
+
+cli({
+  site: "deepseek",
+  name: "detail",
+  description: "Read a specific DeepSeek conversation by ID",
+  domain: "chat.deepseek.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "id", type: "str", required: true, positional: true }],
+  columns: ["index", "role", "text"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const id = parseDeepSeekConversationId(kwargs.id);
+    await p.goto(deepSeekConversationUrl(id), { settleMs: 1800 });
+    await p.wait(1);
+    const rows = await readVisibleConversation(p, false);
+    if (!rows.length) {
+      throw new Error(
+        `No visible DeepSeek messages found for conversation ${id}.`,
+      );
+    }
+    return rows;
+  },
+});
+
+cli({
+  site: "deepseek",
+  name: "send",
+  description:
+    "Send a prompt to a specific DeepSeek conversation without waiting for a response",
+  domain: "chat.deepseek.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: "id", type: "str", required: true, positional: true },
+    { name: "prompt", type: "str", required: true, positional: true },
+  ],
+  columns: ["status", "injectedText"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const id = parseDeepSeekConversationId(kwargs.id);
+    const prompt = str(kwargs.prompt).trim();
+    if (!prompt) throw new Error("DeepSeek prompt cannot be empty.");
+    await p.goto(deepSeekConversationUrl(id), { settleMs: 1800 });
+    await p.click(INPUT);
+    await p.insertText(prompt);
+    await p.press("Enter");
+    await p.wait(0.6);
+    return [{ status: "success", injectedText: prompt }];
+  },
+});

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)];
+  },
+});