@zenalexa/unicli 0.219.0 → 0.220.1

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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { mapJikanRows } from "./web.js";
+
+describe("jikan public commands", () => {
+  it("registers MAL search surfaces", () => {
+    expect(
+      Object.keys(resolveCommand("jikan", "anime")!.adapter.commands),
+    ).toEqual(
+      expect.arrayContaining(["anime", "manga", "characters", "people"]),
+    );
+  });
+
+  it("exposes year and sort controls for 2024-2026 media lookup", () => {
+    expect(resolveCommand("jikan", "anime")!.command.adapterArgs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "year", type: "int" }),
+        expect.objectContaining({
+          name: "sort",
+          choices: expect.arrayContaining(["score", "popularity", "recent"]),
+        }),
+      ]),
+    );
+  });
+
+  it("maps rows", () => {
+    expect(
+      mapJikanRows(
+        [
+          {
+            mal_id: 141632,
+            name: "Hanabi",
+            name_kanji: "花火",
+            favorites: 10,
+            url: "https://myanimelist.net/character/141632/Hanabi",
+          },
+        ],
+        "characters",
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        id: 141632,
+        kind: "characters",
+        title: "Hanabi",
+        title_japanese: "花火",
+      },
+    ]);
+  });
+});

package/src/adapters/jikan/web.ts

@@ -0,0 +1,177 @@
+/**
+ * @owner   src/adapters/jikan/web.ts
+ * @does    Register Jikan public MyAnimeList search commands for anime, manga, characters, and people.
+ * @needs   Jikan v4 public REST API and MAL entity URL formats.
+ * @feeds   ACG title, character, and creator discovery.
+ * @breaks  Jikan throttling or response field changes can block MyAnimeList-backed lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const API = "https://api.jikan.moe/v4";
+
+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(`jikan ${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 > 25) {
+    throw new Error("jikan limit must be an integer in [1, 25].");
+  }
+  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("jikan year must be an integer in [1900, 2100].");
+  }
+  return n;
+}
+
+const SORTS: Record<string, { orderBy: string; direction: string }> = {
+  score: { orderBy: "score", direction: "desc" },
+  popularity: { orderBy: "popularity", direction: "asc" },
+  recent: { orderBy: "start_date", direction: "desc" },
+  relevance: { orderBy: "", direction: "" },
+};
+
+function sortSpec(value: unknown): { orderBy: string; direction: string } {
+  const key = String(value ?? "relevance").trim();
+  const spec = SORTS[key];
+  if (!spec) {
+    throw new Error(
+      `jikan sort must be one of: ${Object.keys(SORTS).join(", ")}.`,
+    );
+  }
+  return spec;
+}
+
+async function fetchJikan(
+  path: string,
+  query: string,
+  limit: number,
+  kwargs: Record<string, unknown>,
+): Promise<unknown[]> {
+  const url = new URL(`${API}/${path}`);
+  url.searchParams.set("q", query);
+  url.searchParams.set("limit", String(limit));
+  if (path === "anime" || path === "manga") {
+    const year = optionalYear(kwargs.year);
+    if (year) {
+      url.searchParams.set("start_date", `${year}-01-01`);
+      url.searchParams.set("end_date", `${year}-12-31`);
+    }
+    const sort = sortSpec(kwargs.sort);
+    if (sort.orderBy) {
+      url.searchParams.set("order_by", sort.orderBy);
+      url.searchParams.set("sort", sort.direction);
+    }
+  }
+  const response = await fetch(url, {
+    headers: { Accept: "application/json", "User-Agent": USER_AGENT },
+  });
+  if (!response.ok)
+    throw new Error(`jikan request failed with HTTP ${response.status}.`);
+  const data = (await response.json()) as { data?: unknown[] };
+  return data.data ?? [];
+}
+
+export function mapJikanRows(
+  rows: unknown[],
+  kind: string,
+): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const images = item.images as { jpg?: { image_url?: string } } | undefined;
+    return {
+      rank: index + 1,
+      id: item.mal_id ?? null,
+      kind,
+      title: str(item.title ?? item.name),
+      title_japanese: str(item.title_japanese ?? item.name_kanji),
+      type: str(item.type),
+      score: item.score ?? null,
+      members: item.members ?? item.favorites ?? null,
+      url: str(item.url),
+      image: str(images?.jpg?.image_url),
+    };
+  });
+}
+
+async function search(
+  kind: "anime" | "manga" | "characters" | "people",
+  kwargs: Record<string, unknown>,
+) {
+  const query = required(kwargs.query, "query");
+  const cap = requireLimit(kwargs.limit);
+  const rows = mapJikanRows(await fetchJikan(kind, query, cap, kwargs), kind);
+  if (rows.length === 0)
+    throw new Error(`No Jikan ${kind} found for "${query}".`);
+  return rows;
+}
+
+const ENTITY_ARGS = [
+  { name: "query", type: "str" as const, required: true, positional: true },
+  { name: "limit", type: "int" as const, default: 10 },
+];
+const MEDIA_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: "relevance",
+    choices: ["relevance", "score", "popularity", "recent"],
+  },
+];
+const COLUMNS = [
+  "rank",
+  "id",
+  "kind",
+  "title",
+  "title_japanese",
+  "type",
+  "score",
+  "members",
+  "url",
+];
+
+for (const name of ["anime", "manga"] as const) {
+  cli({
+    site: "jikan",
+    name,
+    description: `Search MyAnimeList ${name} through Jikan by Japanese name, romaji, or alias`,
+    domain: "api.jikan.moe",
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: MEDIA_ARGS,
+    columns: COLUMNS,
+    func: async (_page, kwargs) => search(name, kwargs),
+  });
+}
+
+for (const name of ["characters", "people"] as const) {
+  cli({
+    site: "jikan",
+    name,
+    description: `Search MyAnimeList ${name} through Jikan by Japanese name, romaji, or alias`,
+    domain: "api.jikan.moe",
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: ENTITY_ARGS,
+    columns: COLUMNS,
+    func: async (_page, kwargs) => search(name, kwargs),
+  });
+}

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { mapKitsuMedia } from "./web.js";
+
+describe("kitsu public commands", () => {
+  it("registers anime and manga commands", () => {
+    expect(
+      Object.keys(resolveCommand("kitsu", "anime")!.adapter.commands),
+    ).toEqual(expect.arrayContaining(["anime", "manga"]));
+  });
+
+  it("maps media rows", () => {
+    expect(
+      mapKitsuMedia([
+        {
+          id: "12794",
+          type: "anime",
+          attributes: {
+            canonicalTitle: "Fireworks",
+            slug: "uchiage-hanabi",
+            subtype: "movie",
+          },
+        },
+      ]),
+    ).toMatchObject([
+      { rank: 1, id: "12794", title: "Fireworks", subtype: "movie" },
+    ]);
+  });
+});

package/src/adapters/kitsu/web.ts

@@ -0,0 +1,109 @@
+/**
+ * @owner   src/adapters/kitsu/web.ts
+ * @does    Register Kitsu public anime and manga search commands.
+ * @needs   Kitsu JSON:API text filters and public media pages.
+ * @feeds   ACG title discovery with community rating and subtype metadata.
+ * @breaks  Kitsu JSON:API field changes or service availability can block lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const API = "https://kitsu.io/api/edge";
+
+function str(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function required(value: unknown): string {
+  const text = str(value).trim();
+  if (!text) throw new Error("kitsu query 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 > 20) {
+    throw new Error("kitsu limit must be an integer in [1, 20].");
+  }
+  return n;
+}
+
+export function mapKitsuMedia(rows: unknown[]): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const attrs =
+      (item.attributes as Record<string, unknown> | undefined) ?? {};
+    const titles = (attrs.titles as Record<string, unknown> | undefined) ?? {};
+    return {
+      rank: index + 1,
+      id: item.id,
+      type: item.type,
+      title: str(
+        attrs.canonicalTitle || titles.en || titles.en_jp || titles.ja_jp,
+      ),
+      subtype: str(attrs.subtype),
+      status: str(attrs.status),
+      start_date: str(attrs.startDate),
+      average_rating: str(attrs.averageRating),
+      popularity_rank: attrs.popularityRank ?? null,
+      synopsis: str(attrs.synopsis).slice(0, 500),
+      url: `https://kitsu.io/${item.type}/${attrs.slug || item.id}`,
+    };
+  });
+}
+
+async function search(
+  kind: "anime" | "manga",
+  kwargs: Record<string, unknown>,
+) {
+  const query = required(kwargs.query);
+  const cap = requireLimit(kwargs.limit);
+  const url = new URL(`${API}/${kind}`);
+  url.searchParams.set("filter[text]", query);
+  url.searchParams.set("page[limit]", String(cap));
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.api+json",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok)
+    throw new Error(`kitsu request failed with HTTP ${response.status}.`);
+  const data = (await response.json()) as { data?: unknown[] };
+  const rows = mapKitsuMedia(data.data ?? []);
+  if (rows.length === 0)
+    throw new Error(`No Kitsu ${kind} found for "${query}".`);
+  return rows;
+}
+
+const ARGS = [
+  { name: "query", type: "str" as const, required: true, positional: true },
+  { name: "limit", type: "int" as const, default: 10 },
+];
+const COLUMNS = [
+  "rank",
+  "id",
+  "type",
+  "title",
+  "subtype",
+  "status",
+  "start_date",
+  "average_rating",
+  "url",
+];
+
+for (const name of ["anime", "manga"] as const) {
+  cli({
+    site: "kitsu",
+    name,
+    description: `Search Kitsu ${name} by Japanese title, romaji, alias, or keyword`,
+    domain: "kitsu.io",
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: ARGS,
+    columns: COLUMNS,
+    func: async (_page, kwargs) => search(name, kwargs),
+  });
+}

package/src/adapters/konachan/detail.yaml

@@ -0,0 +1,62 @@
+site: konachan
+name: detail
+description: Get Konachan post detail by post id
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/post.json"
+      params:
+        tags: "${{ 'id:' + args.id }}"
+        limit: 1
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Konachan post found for this id."
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      author: "${{ item.author }}"
+      created_at: "${{ item.created_at }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      file_ext: "${{ item.file_ext }}"
+      file_size: "${{ item.file_size }}"
+      tags: "${{ item.tags }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_url }}"
+      sample_url: "${{ item.sample_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://konachan.com/post/show/' + item.id }}"
+
+columns:
+  [
+    id,
+    rating,
+    score,
+    author,
+    width,
+    height,
+    tags,
+    source,
+    sample_url,
+    file_url,
+    url,
+  ]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/konachan/download.yaml

@@ -0,0 +1,55 @@
+site: konachan
+name: download
+description: Download Konachan post image by post id
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+  output:
+    type: str
+    default: "./downloads/konachan"
+    description: Output directory
+    x-unicli-kind: path
+  quality:
+    type: str
+    default: sample
+    description: sample or original
+
+columns: [id, rating, tags, url, _download]
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/post.json"
+      params:
+        tags: "${{ 'id:' + args.id }}"
+        limit: 1
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Konachan post found for this id."
+
+  - download:
+      url: "${{ args.quality === 'original' ? item.file_url : item.sample_url }}"
+      dir: "${{ args.output }}"
+      filename: "${{ item.id }}.${{ (args.quality === 'original' ? item.file_url : item.sample_url) | ext | default('jpg') }}"
+      type: image
+      concurrency: 1
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      tags: "${{ item.tags }}"
+      url: "${{ 'https://konachan.com/post/show/' + item.id }}"
+      _download: "${{ item._download }}"
+
+capabilities: ["http.fetch", "http.download"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/konachan/search.yaml

@@ -0,0 +1,65 @@
+site: konachan
+name: search
+description: Search Konachan illustration posts by Japanese, romaji, or Moebooru tag query
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  tags:
+    type: str
+    required: true
+    positional: true
+    description: Tag query, for example "rating:safe" or "sparkle_(honkai:_star_rail)"
+  limit:
+    type: int
+    default: 20
+  page:
+    type: int
+    default: 1
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/post.json"
+      params:
+        tags: "${{ args.tags }}"
+        limit: "${{ args.limit }}"
+        page: "${{ args.page }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      author: "${{ item.author }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      tags: "${{ item.tags }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_url }}"
+      sample_url: "${{ item.sample_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://konachan.com/post/show/' + item.id }}"
+
+columns:
+  [
+    rank,
+    id,
+    rating,
+    score,
+    author,
+    width,
+    height,
+    tags,
+    source,
+    sample_url,
+    file_url,
+    url,
+  ]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/konachan/tags.yaml

@@ -0,0 +1,40 @@
+site: konachan
+name: tags
+description: Search Konachan tags by Japanese name, romaji, or tag prefix
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/tag.json"
+      params:
+        name: "${{ args.query }}"
+        limit: "${{ args.limit }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      name: "${{ item.name }}"
+      count: "${{ item.count }}"
+      type: "${{ item.type }}"
+      ambiguous: "${{ item.ambiguous }}"
+      url: "${{ 'https://konachan.com/post?tags=' + encodeURIComponent(item.name) }}"
+
+columns: [rank, id, name, count, type, ambiguous, url]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/lichess/players.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatLichessTimestamp,
+  mapLichessTopRows,
+  mapLichessUserRow,
+  requireLichessLimit,
+  requireLichessPerf,
+  requireLichessUsername,
+} from "./players.js";
+
+describe("lichess agent-facing player commands", () => {
+  it("validates usernames, perf names, and limits", () => {
+    expect(requireLichessUsername(" DrNykterstein ")).toBe("DrNykterstein");
+    expect(() => requireLichessUsername("x")).toThrow("2-30");
+    expect(requireLichessPerf("blitz")).toBe("blitz");
+    expect(() => requireLichessPerf("bughouse")).toThrow("must be one of");
+    expect(requireLichessLimit(undefined, 10)).toBe(10);
+    expect(requireLichessLimit("200", 10)).toBe(200);
+    expect(() => requireLichessLimit("201", 10)).toThrow(
+      "limit must be an integer",
+    );
+  });
+
+  it("maps leaderboard rows for a selected perf", () => {
+    expect(
+      mapLichessTopRows(
+        {
+          users: [
+            {
+              username: "DrNykterstein",
+              id: "drnykterstein",
+              title: "GM",
+              patron: true,
+              perfs: { blitz: { rating: 3100, progress: 12 } },
+            },
+          ],
+        },
+        "blitz",
+        10,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        username: "DrNykterstein",
+        id: "drnykterstein",
+        title: "GM",
+        rating: 3100,
+        progress: 12,
+        patron: true,
+        url: "https://lichess.org/@/DrNykterstein/perf/blitz",
+      },
+    ]);
+    expect(() => mapLichessTopRows({ users: [] }, "rapid", 10)).toThrow(
+      "no leaderboard rows",
+    );
+  });
+
+  it("maps user profiles and picks the most-played perf", () => {
+    expect(formatLichessTimestamp(1760000000000)).toBe(
+      "2025-10-09T08:53:20.000Z",
+    );
+    expect(
+      mapLichessUserRow(
+        {
+          username: "DrNykterstein",
+          id: "drnykterstein",
+          title: "GM",
+          patron: true,
+          online: true,
+          createdAt: 1760000000000,
+          seenAt: 1760000100000,
+          count: { all: 10, win: 6, loss: 3, draw: 1 },
+          perfs: {
+            bullet: { rating: 3200, games: 50 },
+            blitz: { rating: 3100, games: 100 },
+            puzzle: { rating: 2800, games: 999 },
+          },
+          profile: {
+            fideRating: 2882,
+            country: "NO",
+            bio: "World champion",
+          },
+        },
+        "drnykterstein",
+      ),
+    ).toMatchObject({
+      username: "DrNykterstein",
+      topPerfName: "blitz",
+      topPerfRating: 3100,
+      topPerfGames: 100,
+      gamesAll: 10,
+      country: "NO",
+      url: "https://lichess.org/@/DrNykterstein",
+    });
+    expect(() => mapLichessUserRow({ disabled: true }, "closed")).toThrow(
+      "closed or disabled",
+    );
+  });
+});