@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/arxiv/papers.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeArxivEntities,
+  parseArxivEntries,
+  requireArxivAuthor,
+  requireArxivCategory,
+  requireArxivLimit,
+} from "./papers.js";
+
+describe("arxiv agent-facing author and recent commands", () => {
+  it("validates author, category, and limit inputs", () => {
+    expect(requireArxivAuthor(" Yoshua Bengio ")).toBe("Yoshua Bengio");
+    expect(() => requireArxivAuthor("")).toThrow("cannot be empty");
+    expect(requireArxivCategory("cs.CL")).toBe("cs.CL");
+    expect(requireArxivCategory("q-bio.NC")).toBe("q-bio.NC");
+    expect(() => requireArxivCategory("../cs.CL")).toThrow("Invalid arXiv");
+    expect(requireArxivLimit(undefined, 20)).toBe(20);
+    expect(requireArxivLimit("50", 20)).toBe(50);
+    expect(() => requireArxivLimit("51", 20)).toThrow("arxiv limit");
+  });
+
+  it("decodes entities and parses Atom entries", () => {
+    expect(decodeArxivEntities("A &amp; B &lt; C")).toBe("A & B < C");
+    expect(
+      parseArxivEntries(`
+        <feed>
+          <entry>
+            <id>http://arxiv.org/abs/1706.03762v7</id>
+            <title> Attention   Is All You Need </title>
+            <summary> We present   transformers. </summary>
+            <published>2017-06-12T17:57:34Z</published>
+            <updated>2023-08-02T00:00:00Z</updated>
+            <author><name>Alice &amp; Bob</name></author>
+            <author><name>Carol</name></author>
+            <arxiv:primary_category term="cs.CL" />
+            <category term="cs.CL" />
+            <category term="cs.LG" />
+            <arxiv:comment>15 pages</arxiv:comment>
+            <link title="pdf" href="https://arxiv.org/pdf/1706.03762" rel="related" />
+          </entry>
+        </feed>
+      `),
+    ).toEqual([
+      {
+        id: "1706.03762",
+        title: "Attention Is All You Need",
+        authors: "Alice & Bob, Carol",
+        abstract: "We present transformers.",
+        published: "2017-06-12",
+        updated: "2023-08-02",
+        primary_category: "cs.CL",
+        categories: "cs.CL, cs.LG",
+        comment: "15 pages",
+        pdf: "https://arxiv.org/pdf/1706.03762",
+        url: "https://arxiv.org/abs/1706.03762",
+      },
+    ]);
+  });
+});

package/src/adapters/arxiv/papers.ts

@@ -0,0 +1,226 @@
+/**
+ * @owner   src/adapters/arxiv/papers.ts
+ * @does    Register agent-facing arXiv author and recent category commands.
+ * @needs   export.arxiv.org Atom API, category validation, conservative XML parsing.
+ * @feeds   surface coverage ledger, scholarly search workflow, arXiv category monitoring.
+ * @breaks  arXiv Atom shape drift, weak category parsing, or silent empty feeds hide paper discovery failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const ARXIV_BASE = "https://export.arxiv.org/api/query";
+const CATEGORY_RE = /^[a-z]+(?:-[a-z]+)*(?:\.[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)?$/;
+
+interface ArxivEntry {
+  id: string;
+  title: string;
+  authors: string;
+  abstract: string;
+  published: string;
+  updated: string;
+  primary_category: string;
+  categories: string;
+  comment: string;
+  pdf: string;
+  url: string;
+}
+
+export function requireArxivLimit(
+  value: unknown,
+  fallback: number,
+  max = 50,
+): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > max) {
+    throw new Error(`arxiv limit must be an integer in [1, ${max}].`);
+  }
+  return n;
+}
+
+export function requireArxivAuthor(value: unknown): string {
+  const author = String(value ?? "").trim();
+  if (!author) throw new Error("arxiv author cannot be empty.");
+  return author;
+}
+
+export function requireArxivCategory(value: unknown): string {
+  const category = String(value ?? "").trim();
+  if (!CATEGORY_RE.test(category)) {
+    throw new Error(`Invalid arXiv category "${String(value)}".`);
+  }
+  return category;
+}
+
+export function decodeArxivEntities(value: string): string {
+  return value
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#39;/g, "'");
+}
+
+function extractFirst(xml: string, tag: string): string {
+  const match = xml.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`));
+  return match ? match[1].trim() : "";
+}
+
+function extractAll(xml: string, tag: string): string[] {
+  const out: string[] = [];
+  const re = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, "g");
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml)) !== null) out.push(match[1].trim());
+  return out;
+}
+
+function extractAttr(xml: string, tag: string, attr: string): string {
+  const match = xml.match(new RegExp(`<${tag}\\b[^>]*?\\b${attr}="([^"]*)"`));
+  return match ? match[1] : "";
+}
+
+function extractAllAttr(xml: string, tag: string, attr: string): string[] {
+  const out: string[] = [];
+  const re = new RegExp(`<${tag}\\b[^>]*?\\b${attr}="([^"]*)"`, "g");
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml)) !== null) out.push(match[1]);
+  return out;
+}
+
+function findLinkHref(xml: string, rel: string): string {
+  const re = /<link\b([^>]*)\/?>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml)) !== null) {
+    const attrs = match[1];
+    if (!new RegExp(`\\brel="${rel}"`).test(attrs)) continue;
+    const href = attrs.match(/\bhref="([^"]*)"/);
+    if (href) return href[1];
+  }
+  return "";
+}
+
+export function parseArxivEntries(xml: string): ArxivEntry[] {
+  const out: ArxivEntry[] = [];
+  const re = /<entry>([\s\S]*?)<\/entry>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml)) !== null) {
+    const entry = match[1];
+    const rawId = extractFirst(entry, "id");
+    const id = rawId
+      .replace(/^https?:\/\/arxiv\.org\/abs\//, "")
+      .replace(/v\d+$/, "");
+    const title = decodeArxivEntities(
+      extractFirst(entry, "title").replace(/\s+/g, " "),
+    ).trim();
+    out.push({
+      id,
+      title,
+      authors: decodeArxivEntities(extractAll(entry, "name").join(", ")),
+      abstract: decodeArxivEntities(
+        extractFirst(entry, "summary").replace(/\s+/g, " "),
+      ).trim(),
+      published: extractFirst(entry, "published").slice(0, 10),
+      updated: extractFirst(entry, "updated").slice(0, 10),
+      primary_category: extractAttr(entry, "arxiv:primary_category", "term"),
+      categories: extractAllAttr(entry, "category", "term").join(", "),
+      comment: decodeArxivEntities(
+        extractFirst(entry, "arxiv:comment").replace(/\s+/g, " "),
+      ).trim(),
+      pdf: findLinkHref(entry, "related") || `https://arxiv.org/pdf/${id}`,
+      url: `https://arxiv.org/abs/${id}`,
+    });
+  }
+  return out;
+}
+
+async function fetchArxiv(params: URLSearchParams): Promise<string> {
+  const response = await fetch(`${ARXIV_BASE}?${params.toString()}`, {
+    headers: {
+      "User-Agent": "unicli-arxiv/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/atom+xml, application/xml, text/xml",
+    },
+  });
+  if (!response.ok)
+    throw new Error(`arXiv API returned HTTP ${response.status}.`);
+  return response.text();
+}
+
+function compactRows(entries: ArxivEntry[]): Array<Record<string, unknown>> {
+  return entries.map((entry) => ({
+    id: entry.id,
+    title: entry.title,
+    authors: entry.authors,
+    published: entry.published,
+    primary_category: entry.primary_category,
+    url: entry.url,
+  }));
+}
+
+cli({
+  site: "arxiv",
+  name: "author",
+  description: "List arXiv papers by a given author",
+  domain: "export.arxiv.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "author",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Author name",
+    },
+    { name: "limit", type: "int", default: 20, description: "Max papers" },
+  ],
+  columns: ["id", "title", "authors", "published", "primary_category", "url"],
+  func: async (_page, kwargs) => {
+    const author = requireArxivAuthor(kwargs.author);
+    const limit = requireArxivLimit(kwargs.limit, 20);
+    const params = new URLSearchParams({
+      search_query: `au:"${author}"`,
+      max_results: String(limit),
+      sortBy: "submittedDate",
+      sortOrder: "descending",
+    });
+    const rows = compactRows(parseArxivEntries(await fetchArxiv(params)));
+    if (rows.length === 0) {
+      throw new Error(`No arXiv papers found for author "${author}".`);
+    }
+    return rows;
+  },
+});
+
+cli({
+  site: "arxiv",
+  name: "recent",
+  description: "List recent arXiv submissions in a category",
+  domain: "export.arxiv.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "category",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "arXiv category",
+    },
+    { name: "limit", type: "int", default: 10, description: "Max papers" },
+  ],
+  columns: ["id", "title", "authors", "published", "primary_category", "url"],
+  func: async (_page, kwargs) => {
+    const category = requireArxivCategory(kwargs.category);
+    const limit = requireArxivLimit(kwargs.limit, 10);
+    const params = new URLSearchParams({
+      search_query: `cat:${category}`,
+      max_results: String(limit),
+      sortBy: "submittedDate",
+      sortOrder: "descending",
+    });
+    const rows = compactRows(parseArxivEntries(await fetchArxiv(params)));
+    if (rows.length === 0) {
+      throw new Error(`No recent arXiv papers found in ${category}.`);
+    }
+    return rows;
+  },
+});

package/src/adapters/bangumi/web.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import {
+  bangumiSubjectSearchBody,
+  mapBangumiCharacters,
+  mapBangumiSubject,
+  mapBangumiSubjects,
+} from "./web.js";
+
+describe("bangumi public commands", () => {
+  it("registers subject commands", () => {
+    expect(
+      Object.keys(resolveCommand("bangumi", "anime")!.adapter.commands),
+    ).toEqual(
+      expect.arrayContaining([
+        "anime",
+        "book",
+        "game",
+        "subject",
+        "characters",
+      ]),
+    );
+  });
+
+  it("exposes year and sort filters on subject commands", () => {
+    const args = resolveCommand("bangumi", "game")!.command.adapterArgs;
+
+    expect(args).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "year", type: "int" }),
+        expect.objectContaining({
+          name: "sort",
+          choices: ["match", "rank", "score", "heat"],
+        }),
+      ]),
+    );
+  });
+
+  it("builds v0 subject search bodies with type, year, and sort filters", () => {
+    expect(
+      bangumiSubjectSearchBody("game", {
+        query: "学園アイドルマスター",
+        year: 2024,
+        sort: "rank",
+      }),
+    ).toEqual({
+      keyword: "学園アイドルマスター",
+      sort: "rank",
+      filter: {
+        type: [4],
+        air_date: [">=2024-01-01", "<2025-01-01"],
+      },
+    });
+  });
+
+  it("maps search rows", () => {
+    expect(
+      mapBangumiSubjects([
+        {
+          id: 344272,
+          type: 4,
+          name: "PARQUET",
+          name_cn: "",
+          url: "http://bgm.tv/subject/344272",
+        },
+      ]),
+    ).toMatchObject([{ rank: 1, id: 344272, name: "PARQUET" }]);
+  });
+
+  it("maps subject detail", () => {
+    expect(
+      mapBangumiSubject({
+        id: 344272,
+        name: "PARQUET",
+        platform: "游戏",
+        rating: { score: 6.7, total: 200 },
+      }),
+    ).toMatchObject({
+      id: 344272,
+      name: "PARQUET",
+      platform: "游戏",
+      score: 6.7,
+    });
+  });
+
+  it("maps character rows", () => {
+    expect(
+      mapBangumiCharacters([
+        {
+          id: 148287,
+          name: "花火",
+          gender: "female",
+          stat: { comments: 21, collects: 59 },
+          summary: "假面愚者",
+        },
+      ]),
+    ).toMatchObject([
+      {
+        rank: 1,
+        id: 148287,
+        name: "花火",
+        gender: "female",
+        comments: 21,
+        collects: 59,
+        url: "https://bgm.tv/character/148287",
+      },
+    ]);
+  });
+});

package/src/adapters/bangumi/web.ts

@@ -0,0 +1,295 @@
+/**
+ * @owner   src/adapters/bangumi/web.ts
+ * @does    Register Bangumi public search/detail commands for anime, books, games, subjects, and characters.
+ * @needs   Bangumi public REST/search endpoints and user-agent policy.
+ * @feeds   Chinese/Japanese ACG title, character, and visual-novel discovery.
+ * @breaks  Bangumi legacy search endpoint or v0 subject/character schema changes can block lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const API = "https://api.bgm.tv";
+
+function str(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function required(value: unknown, label: string): string {
+  const text = str(value).trim();
+  if (!text) throw new Error(`bangumi ${label} cannot be empty.`);
+  return text;
+}
+
+function requireLimit(value: unknown): number {
+  if (value === undefined || value === null || value === "") return 10;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 50) {
+    throw new Error("bangumi limit must be an integer in [1, 50].");
+  }
+  return n;
+}
+
+function optionalYear(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1900 || n > 2100) {
+    throw new Error("bangumi year must be an integer in [1900, 2100].");
+  }
+  return n;
+}
+
+const TYPE_CODES: Record<string, number> = {
+  book: 1,
+  anime: 2,
+  music: 3,
+  game: 4,
+  real: 6,
+};
+const SORTS = new Set(["match", "rank", "score", "heat"]);
+
+function normalizeSort(value: unknown): string {
+  const sort = str(value || "match")
+    .trim()
+    .toLowerCase();
+  if (!SORTS.has(sort)) {
+    throw new Error("bangumi sort must be one of: match, rank, score, heat.");
+  }
+  return sort;
+}
+
+async function getJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok)
+    throw new Error(`bangumi request failed with HTTP ${response.status}.`);
+  return response.json();
+}
+
+async function postJson(url: string, body: unknown): Promise<unknown> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok)
+    throw new Error(`bangumi request failed with HTTP ${response.status}.`);
+  return response.json();
+}
+
+export function mapBangumiSubjects(rows: unknown[]): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const rating = item.rating as Record<string, unknown> | undefined;
+    const images = item.images as Record<string, unknown> | undefined;
+    return {
+      rank: index + 1,
+      id: item.id,
+      type: item.type,
+      name: str(item.name),
+      name_cn: str(item.name_cn),
+      date: str(item.air_date ?? item.date),
+      score: rating?.score ?? null,
+      rank_site: item.rank ?? null,
+      summary: str(item.summary).slice(0, 500),
+      image: str(images?.common),
+      url: str(item.url) || `https://bgm.tv/subject/${item.id}`,
+    };
+  });
+}
+
+export function mapBangumiSubject(
+  item: Record<string, unknown>,
+): Record<string, unknown> {
+  const rating = item.rating as Record<string, unknown> | undefined;
+  const images = item.images as Record<string, unknown> | undefined;
+  return {
+    id: item.id,
+    type: item.type,
+    name: str(item.name),
+    name_cn: str(item.name_cn),
+    platform: str(item.platform),
+    date: str(item.date),
+    score: rating?.score ?? null,
+    total_votes: rating?.total ?? null,
+    rank_site: item.rank ?? null,
+    summary: str(item.summary).slice(0, 1500),
+    image: str(images?.common),
+    url: `https://bgm.tv/subject/${item.id}`,
+  };
+}
+
+export function mapBangumiCharacters(
+  rows: unknown[],
+): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const stat = item.stat as Record<string, unknown> | undefined;
+    const images = item.images as Record<string, unknown> | undefined;
+    return {
+      rank: index + 1,
+      id: item.id,
+      name: str(item.name),
+      gender: str(item.gender),
+      type: item.type ?? null,
+      comments: stat?.comments ?? null,
+      collects: stat?.collects ?? null,
+      summary: str(item.summary).slice(0, 700),
+      image: str(images?.medium ?? images?.grid),
+      url: `https://bgm.tv/character/${item.id}`,
+    };
+  });
+}
+
+async function searchSubject(
+  kind: keyof typeof TYPE_CODES,
+  kwargs: Record<string, unknown>,
+) {
+  const cap = requireLimit(kwargs.limit);
+  const url = new URL(`${API}/v0/search/subjects`);
+  url.searchParams.set("limit", String(cap));
+  url.searchParams.set("offset", "0");
+  const data = (await postJson(
+    url.toString(),
+    bangumiSubjectSearchBody(kind, kwargs),
+  )) as { data?: unknown[] };
+  const rows = mapBangumiSubjects(data.data ?? []);
+  if (rows.length === 0)
+    throw new Error(
+      `No Bangumi ${kind} found for "${required(kwargs.query, "query")}".`,
+    );
+  return rows;
+}
+
+export function bangumiSubjectSearchBody(
+  kind: keyof typeof TYPE_CODES,
+  kwargs: Record<string, unknown>,
+): Record<string, unknown> {
+  const year = optionalYear(kwargs.year);
+  const sort = normalizeSort(kwargs.sort);
+  const filter: Record<string, unknown> = { type: [TYPE_CODES[kind]] };
+  if (year !== undefined) {
+    filter.air_date = [`>=${year}-01-01`, `<${year + 1}-01-01`];
+  }
+  return {
+    keyword: required(kwargs.query, "query"),
+    ...(sort === "match" ? {} : { sort }),
+    filter,
+  };
+}
+
+async function searchCharacters(kwargs: Record<string, unknown>) {
+  const query = required(kwargs.query, "query");
+  const cap = requireLimit(kwargs.limit);
+  const url = new URL(`${API}/v0/search/characters`);
+  url.searchParams.set("limit", String(cap));
+  const data = (await postJson(url.toString(), {
+    keyword: query,
+    filter: {},
+  })) as { data?: unknown[] };
+  const rows = mapBangumiCharacters(data.data ?? []);
+  if (rows.length === 0)
+    throw new Error(`No Bangumi characters found for "${query}".`);
+  return rows;
+}
+
+const SEARCH_ARGS = [
+  { name: "query", type: "str" as const, required: true, positional: true },
+  { name: "limit", type: "int" as const, default: 10 },
+  { name: "year", type: "int" as const },
+  {
+    name: "sort",
+    type: "str" as const,
+    default: "match",
+    choices: ["match", "rank", "score", "heat"],
+    description: "match, rank, score, heat",
+  },
+];
+const CHARACTER_ARGS = SEARCH_ARGS.filter(
+  (arg) => arg.name === "query" || arg.name === "limit",
+);
+const SUBJECT_COLUMNS = [
+  "rank",
+  "id",
+  "type",
+  "name",
+  "name_cn",
+  "date",
+  "score",
+  "rank_site",
+  "url",
+];
+const CHARACTER_COLUMNS = [
+  "rank",
+  "id",
+  "name",
+  "gender",
+  "comments",
+  "collects",
+  "summary",
+  "url",
+];
+
+for (const name of ["anime", "book", "game"] as const) {
+  cli({
+    site: "bangumi",
+    name,
+    description: `Search Bangumi ${name} subjects by Japanese title, Chinese title, romaji, or alias`,
+    domain: "bgm.tv",
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: SEARCH_ARGS,
+    columns: SUBJECT_COLUMNS,
+    func: async (_page, kwargs) => searchSubject(name, kwargs),
+  });
+}
+
+cli({
+  site: "bangumi",
+  name: "characters",
+  description:
+    "Search Bangumi characters by Japanese name, Chinese name, romaji, or alias",
+  domain: "bgm.tv",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: CHARACTER_ARGS,
+  columns: CHARACTER_COLUMNS,
+  func: async (_page, kwargs) => searchCharacters(kwargs),
+});
+
+cli({
+  site: "bangumi",
+  name: "subject",
+  description: "Get Bangumi subject details by subject id",
+  domain: "bgm.tv",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [{ name: "id", type: "str", required: true, positional: true }],
+  columns: [
+    "id",
+    "type",
+    "name",
+    "name_cn",
+    "platform",
+    "date",
+    "score",
+    "rank_site",
+    "summary",
+    "url",
+  ],
+  func: async (_page, kwargs) => [
+    mapBangumiSubject(
+      (await getJson(
+        `${API}/v0/subjects/${required(kwargs.id, "id")}`,
+      )) as Record<string, unknown>,
+    ),
+  ],
+});