@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/rfc/rfc.ts

@@ -0,0 +1,133 @@
+/**
+ * @owner   src/adapters/rfc/rfc.ts
+ * @does    Register agent-facing IETF RFC metadata command.
+ * @needs   IETF datatracker public API, strict RFC number validation, date normalization.
+ * @feeds   surface coverage ledger, RFC metadata rows, standards cross-reference URLs.
+ * @breaks  Datatracker API drift, weak number parsing, or silent empty rows hide RFC metadata failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://datatracker.ietf.org";
+
+export function requireRfcNumber(value: unknown): number {
+  const text = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^rfc/, "");
+  if (!text) throw new Error("rfc number cannot be empty.");
+  if (!/^\d+$/.test(text))
+    throw new Error(`rfc number "${String(value)}" is not valid.`);
+  const number = Number(text);
+  if (!Number.isInteger(number) || number < 1 || number > 999_999) {
+    throw new Error("rfc number must be an integer in [1, 999999].");
+  }
+  return number;
+}
+
+export function trimRfcDate(value: unknown): string | null {
+  const text = String(value ?? "").trim();
+  return /^\d{4}-\d{2}-\d{2}/.test(text) ? text.slice(0, 10) : null;
+}
+
+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 objectField(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function mapRfcRow(
+  number: number,
+  doc: Record<string, unknown>,
+): Record<string, unknown> {
+  const authors = Array.isArray(doc.authors)
+    ? doc.authors
+        .map((author) => stringField(objectField(author).name))
+        .filter(Boolean)
+        .join(", ")
+    : "";
+  const group = objectField(doc.group);
+  const name = `rfc${number}`;
+  return {
+    rfc: number,
+    title: stringField(doc.title),
+    state: stringField(doc.state),
+    stdLevel: stringField(doc.std_level),
+    group: stringField(group.name),
+    groupType: stringField(group.type),
+    pages: numberField(doc.pages),
+    published: trimRfcDate(doc.time),
+    authors,
+    abstract: stringField(doc.abstract),
+    rfcEditorUrl: `https://www.rfc-editor.org/rfc/rfc${number}`,
+    url: `${API_BASE}/doc/${name}/`,
+  };
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-rfc (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  });
+  if (response.status === 404) throw new Error(`${label} returned no result.`);
+  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: "rfc",
+  name: "rfc",
+  description: "Fetch IETF RFC metadata by RFC number",
+  domain: "datatracker.ietf.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "number",
+      type: "int",
+      required: true,
+      positional: true,
+      description: "RFC number",
+    },
+  ],
+  columns: [
+    "rfc",
+    "title",
+    "state",
+    "stdLevel",
+    "group",
+    "groupType",
+    "pages",
+    "published",
+    "authors",
+    "abstract",
+    "rfcEditorUrl",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const number = requireRfcNumber(kwargs.number);
+    const doc = objectField(
+      await fetchJson(`${API_BASE}/doc/rfc${number}/doc.json`, "rfc rfc"),
+    );
+    if (!doc.name)
+      throw new Error(`rfc rfc returned no metadata for RFC ${number}.`);
+    return [mapRfcRow(number, doc)];
+  },
+});

package/src/adapters/rubygems/gem.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { mapRubyGemRow, requireGemName } from "./gem.js";
+
+describe("rubygems agent-facing gem command", () => {
+  it("validates gem tokens", () => {
+    expect(requireGemName(" rails ")).toBe("rails");
+    expect(() => requireGemName("../rails")).toThrow("gem name must be");
+  });
+
+  it("maps gem metadata with source and bug tracker fallbacks", () => {
+    expect(
+      mapRubyGemRow(
+        {
+          name: "rails",
+          version: "8.0.0",
+          version_created_at: "2026-05-01T00:00:00.000Z",
+          downloads: 1000,
+          version_downloads: 100,
+          licenses: ["MIT"],
+          authors: "DHH",
+          homepage_uri: "https://rubyonrails.org",
+          metadata: {
+            source_code_uri: "https://github.com/rails/rails",
+            bug_tracker_uri: "https://github.com/rails/rails/issues",
+          },
+          info: "Rails is a framework",
+          project_uri: "https://rubygems.org/gems/rails",
+        },
+        "rails",
+      ),
+    ).toMatchObject({
+      gem: "rails",
+      version: "8.0.0",
+      releasedAt: "2026-05-01",
+      downloads: 1000,
+      versionDownloads: 100,
+      license: "MIT",
+      authors: "DHH",
+      source: "https://github.com/rails/rails",
+      bugs: "https://github.com/rails/rails/issues",
+    });
+  });
+});

package/src/adapters/rubygems/gem.ts

@@ -0,0 +1,126 @@
+/**
+ * @owner   src/adapters/rubygems/gem.ts
+ * @does    Register agent-facing RubyGems single-gem metadata command.
+ * @needs   rubygems.org public gem JSON API.
+ * @feeds   surface coverage ledger, Ruby dependency inspection, registry command surface.
+ * @breaks  RubyGems envelope drift or weak gem-name validation hides gem metadata.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const GEMS_BASE = "https://rubygems.org/api/v1";
+
+interface RubyGemBody {
+  name?: unknown;
+  version?: unknown;
+  version_created_at?: unknown;
+  downloads?: unknown;
+  version_downloads?: unknown;
+  licenses?: unknown;
+  authors?: unknown;
+  homepage_uri?: unknown;
+  source_code_uri?: unknown;
+  bug_tracker_uri?: unknown;
+  metadata?: Record<string, unknown>;
+  info?: unknown;
+  project_uri?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function numberField(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function requireGemName(value: unknown): string {
+  const name = String(value ?? "").trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+    throw new Error("gem name must be a non-empty RubyGems token.");
+  }
+  return name;
+}
+
+export function mapRubyGemRow(
+  body: RubyGemBody,
+  requested: string,
+): Record<string, unknown> {
+  const name = stringField(body.name) || requested;
+  if (!name) throw new Error(`RubyGems returned no metadata for ${requested}.`);
+  const licenses = Array.isArray(body.licenses)
+    ? body.licenses.map(stringField).filter(Boolean).join(", ")
+    : "";
+  const metadata = body.metadata ?? {};
+  return {
+    gem: name,
+    version: stringField(body.version),
+    releasedAt: stringField(body.version_created_at).slice(0, 10),
+    downloads: numberField(body.downloads),
+    versionDownloads: numberField(body.version_downloads),
+    license: licenses,
+    authors: stringField(body.authors),
+    homepage: stringField(body.homepage_uri),
+    source:
+      stringField(body.source_code_uri) ||
+      stringField(metadata.source_code_uri),
+    bugs:
+      stringField(body.bug_tracker_uri) ||
+      stringField(metadata.bug_tracker_uri),
+    info: stringField(body.info),
+    url: stringField(body.project_uri) || `https://rubygems.org/gems/${name}`,
+  };
+}
+
+async function fetchGemJson(name: string): Promise<unknown> {
+  const response = await fetch(
+    `${GEMS_BASE}/gems/${encodeURIComponent(name)}.json`,
+    {
+      headers: {
+        "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+        Accept: "application/json",
+      },
+    },
+  );
+  if (response.status === 404)
+    throw new Error(`rubygems gem ${name} returned no result.`);
+  if (!response.ok)
+    throw new Error(`rubygems gem ${name} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "rubygems",
+  name: "gem",
+  description: "Fetch RubyGems gem metadata",
+  domain: "rubygems.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "name",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Gem name",
+    },
+  ],
+  columns: [
+    "gem",
+    "version",
+    "releasedAt",
+    "downloads",
+    "versionDownloads",
+    "license",
+    "authors",
+    "homepage",
+    "source",
+    "bugs",
+    "info",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const name = requireGemName(kwargs.name);
+    const body = (await fetchGemJson(name)) as RubyGemBody;
+    return [mapRubyGemRow(body, name)];
+  },
+});

package/src/adapters/safebooru/detail.yaml

@@ -0,0 +1,63 @@
+site: safebooru
+name: detail
+description: Get Safebooru post detail by post id
+domain: safebooru.org
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+
+pipeline:
+  - fetch:
+      url: "https://safebooru.org/index.php"
+      params:
+        page: dapi
+        s: post
+        q: index
+        json: 1
+        id: "${{ args.id }}"
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Safebooru post found for this id."
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      owner: "${{ item.owner }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      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://safebooru.org/index.php?page=post&s=view&id=' + item.id }}"
+
+columns:
+  [
+    id,
+    rating,
+    score,
+    owner,
+    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/safebooru/download.yaml

@@ -0,0 +1,58 @@
+site: safebooru
+name: download
+description: Download Safebooru post image by post id
+domain: safebooru.org
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+  output:
+    type: str
+    default: "./downloads/safebooru"
+    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://safebooru.org/index.php"
+      params:
+        page: dapi
+        s: post
+        q: index
+        json: 1
+        id: "${{ args.id }}"
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Safebooru 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://safebooru.org/index.php?page=post&s=view&id=' + 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/safebooru/search.yaml

@@ -0,0 +1,69 @@
+site: safebooru
+name: search
+description: Search Safebooru illustration posts by Moebooru tag query such as blue_archive rating:safe
+domain: safebooru.org
+type: web-api
+strategy: public
+
+args:
+  tags:
+    type: str
+    required: true
+    positional: true
+    description: Moebooru tag query, for example "blue_archive rating:safe"
+  limit:
+    type: int
+    default: 20
+  page:
+    type: int
+    default: 0
+
+pipeline:
+  - fetch:
+      url: "https://safebooru.org/index.php"
+      params:
+        page: dapi
+        s: post
+        q: index
+        json: 1
+        tags: "${{ args.tags }}"
+        limit: "${{ args.limit }}"
+        pid: "${{ args.page }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      owner: "${{ item.owner }}"
+      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://safebooru.org/index.php?page=post&s=view&id=' + item.id }}"
+
+columns:
+  [
+    rank,
+    id,
+    rating,
+    score,
+    owner,
+    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/safebooru/web.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { mergeSafebooruTags, parseSafebooruTags } from "./web.js";
+
+describe("safebooru tag command", () => {
+  it("registers tags command", () => {
+    expect(
+      Object.keys(resolveCommand("safebooru", "tags")!.adapter.commands),
+    ).toEqual(expect.arrayContaining(["tags"]));
+  });
+
+  it("parses DAPI tag XML", () => {
+    expect(
+      parseSafebooruTags(
+        '<tags><tag type="3" count="108328" name="blue_archive" ambiguous="false" id="1167631"/></tags>',
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        id: "1167631",
+        name: "blue_archive",
+        count: "108328",
+        type: "3",
+        ambiguous: "false",
+      },
+    ]);
+  });
+
+  it("keeps exact tag rows ahead of prefix matches", () => {
+    expect(
+      mergeSafebooruTags([
+        [
+          {
+            rank: 1,
+            id: "1167631",
+            name: "blue_archive",
+            count: "108328",
+            type: "3",
+            ambiguous: "false",
+            url: "https://safebooru.org/index.php?page=post&s=list&tags=blue_archive",
+          },
+        ],
+        [
+          {
+            rank: 1,
+            id: "33300201",
+            name: "blue_archive_2025_hack",
+            count: "22",
+            type: "0",
+            ambiguous: "false",
+            url: "https://safebooru.org/index.php?page=post&s=list&tags=blue_archive_2025_hack",
+          },
+        ],
+      ]),
+    ).toMatchObject([
+      { rank: 1, name: "blue_archive" },
+      { rank: 2, name: "blue_archive_2025_hack" },
+    ]);
+  });
+});

package/src/adapters/safebooru/web.ts

@@ -0,0 +1,130 @@
+/**
+ * @owner   src/adapters/safebooru/web.ts
+ * @does    Register Safebooru tag lookup for exact and prefix-style ACG tag discovery.
+ * @needs   Safebooru DAPI tag XML endpoint.
+ * @feeds   Booru tag discovery before image search/detail/download workflows.
+ * @breaks  Safebooru DAPI XML attribute changes can block tag lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+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(`safebooru ${label} cannot be empty.`);
+  return text;
+}
+
+function requireLimit(value: unknown): number {
+  if (value === undefined || value === null || value === "") return 20;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 100) {
+    throw new Error("safebooru limit must be an integer in [1, 100].");
+  }
+  return n;
+}
+
+function decodeXml(value: string): string {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+function attr(source: string, name: string): string {
+  const match = source.match(new RegExp(`\\b${name}="([^"]*)"`));
+  return match ? decodeXml(match[1]) : "";
+}
+
+export function parseSafebooruTags(xml: string): Record<string, unknown>[] {
+  const rows: Record<string, unknown>[] = [];
+  const tagRegex = /<tag\b[^>]*\/>/g;
+  let match: RegExpExecArray | null;
+  while ((match = tagRegex.exec(xml)) !== null) {
+    const raw = match[0];
+    const name = attr(raw, "name");
+    if (!name) continue;
+    rows.push({
+      rank: rows.length + 1,
+      id: attr(raw, "id"),
+      name,
+      count: attr(raw, "count"),
+      type: attr(raw, "type"),
+      ambiguous: attr(raw, "ambiguous"),
+      url: `https://safebooru.org/index.php?page=post&s=list&tags=${encodeURIComponent(name)}`,
+    });
+  }
+  return rows;
+}
+
+export function mergeSafebooruTags(
+  groups: Record<string, unknown>[][],
+): Record<string, unknown>[] {
+  const rows: Record<string, unknown>[] = [];
+  const seen = new Set<string>();
+  for (const group of groups) {
+    for (const row of group) {
+      const name = str(row.name);
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      rows.push({ ...row, rank: rows.length + 1 });
+    }
+  }
+  return rows;
+}
+
+async function fetchTagRows(url: URL): Promise<Record<string, unknown>[]> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/xml,text/xml",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok)
+    throw new Error(`safebooru request failed with HTTP ${response.status}.`);
+  return parseSafebooruTags(await response.text());
+}
+
+function tagUrl(kind: "name" | "name_pattern", query: string, limit: number) {
+  const url = new URL("https://safebooru.org/index.php");
+  url.searchParams.set("page", "dapi");
+  url.searchParams.set("s", "tag");
+  url.searchParams.set("q", "index");
+  url.searchParams.set(kind, query);
+  url.searchParams.set("limit", String(limit));
+  return url;
+}
+
+async function searchTags(kwargs: Record<string, unknown>) {
+  const query = required(kwargs.query, "query");
+  const limit = requireLimit(kwargs.limit);
+  const rows = mergeSafebooruTags([
+    await fetchTagRows(tagUrl("name", query, 1)),
+    await fetchTagRows(tagUrl("name_pattern", query, limit)),
+  ]).slice(0, limit);
+  if (rows.length === 0)
+    throw new Error(`No Safebooru tags found for "${query}".`);
+  return rows;
+}
+
+cli({
+  site: "safebooru",
+  name: "tags",
+  description:
+    "Search Safebooru tags by exact tag name or ASCII tag prefix such as blue_archive",
+  domain: "safebooru.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["rank", "id", "name", "count", "type", "ambiguous", "url"],
+  func: async (_page, kwargs) => searchTags(kwargs),
+});