@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/rest-countries/countries.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+  joinCountryCurrencies,
+  joinCountryLanguages,
+  mapCountryRows,
+  requireRestCountriesLimit,
+  requireRestCountriesRegion,
+} from "./countries.js";
+
+describe("rest-countries agent-facing commands", () => {
+  it("validates region and limit arguments", () => {
+    expect(requireRestCountriesRegion(" Asia ")).toBe("asia");
+    expect(() => requireRestCountriesRegion("middle-earth")).toThrow(
+      "not supported",
+    );
+    expect(requireRestCountriesLimit(undefined, 25, 250)).toBe(25);
+    expect(requireRestCountriesLimit("250", 25, 250)).toBe(250);
+    expect(() => requireRestCountriesLimit("251", 25, 250)).toThrow(
+      "rest-countries limit must",
+    );
+  });
+
+  it("joins currencies and languages from REST Countries maps", () => {
+    expect(
+      joinCountryCurrencies({
+        JPY: { name: "Japanese yen", symbol: "yen" },
+        USD: {},
+      }),
+    ).toBe("JPY (Japanese yen), USD");
+    expect(joinCountryLanguages({ jpn: "Japanese", eng: "English" })).toBe(
+      "Japanese, English",
+    );
+  });
+
+  it("maps and sorts country rows by population", () => {
+    expect(
+      mapCountryRows(
+        [
+          {
+            name: { common: "Small", official: "Small State" },
+            cca2: "SS",
+            cca3: "SML",
+            population: 10,
+            latlng: [1, 2],
+            capital: ["One"],
+            timezones: ["UTC"],
+            languages: { eng: "English" },
+            currencies: { USD: { name: "United States dollar" } },
+            independent: true,
+            unMember: false,
+            landlocked: true,
+          },
+          {
+            name: { common: "Large", official: "Large State" },
+            cca2: "LS",
+            cca3: "LRG",
+            population: "20",
+          },
+        ],
+        2,
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        commonName: "Large",
+        cca3: "LRG",
+        population: 20,
+        url: "https://restcountries.com/v3.1/alpha/lrg",
+      },
+      {
+        rank: 2,
+        commonName: "Small",
+        latitude: 1,
+        languages: "English",
+        currencies: "USD (United States dollar)",
+        independent: true,
+      },
+    ]);
+  });
+});

package/src/adapters/rest-countries/countries.ts

@@ -0,0 +1,271 @@
+/**
+ * @owner   src/adapters/rest-countries/countries.ts
+ * @does    Register agent-facing REST Countries country and region commands.
+ * @needs   REST Countries v3.1 public API, bounded row limits, validated region names.
+ * @feeds   surface coverage ledger, country metadata rows, public reference data search.
+ * @breaks  REST Countries API drift, unbounded queries, or silent empty rows hide lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://restcountries.com/v3.1";
+const COUNTRY_FIELDS = [
+  "name",
+  "cca2",
+  "cca3",
+  "ccn3",
+  "capital",
+  "region",
+  "subregion",
+  "population",
+  "area",
+  "languages",
+  "currencies",
+  "flag",
+  "latlng",
+  "timezones",
+  "independent",
+  "unMember",
+  "landlocked",
+].join(",");
+const REGIONS = new Set([
+  "africa",
+  "americas",
+  "asia",
+  "europe",
+  "oceania",
+  "antarctic",
+]);
+const COLUMNS = [
+  "rank",
+  "commonName",
+  "officialName",
+  "cca2",
+  "cca3",
+  "ccn3",
+  "capital",
+  "region",
+  "subregion",
+  "population",
+  "area",
+  "languages",
+  "currencies",
+  "latitude",
+  "longitude",
+  "timezones",
+  "independent",
+  "unMember",
+  "landlocked",
+  "flag",
+  "url",
+];
+
+function nonEmptyString(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`rest-countries ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireRestCountriesLimit(
+  value: unknown,
+  fallback: number,
+  max: number,
+  label = "limit",
+): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > max) {
+    throw new Error(
+      `rest-countries ${label} must be an integer in [1, ${max}]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+export function requireRestCountriesRegion(value: unknown): string {
+  const region = nonEmptyString(value, "region").toLowerCase();
+  if (!REGIONS.has(region)) {
+    throw new Error(
+      `rest-countries region "${String(value)}" is not supported. Allowed: ${[...REGIONS].join(", ")}.`,
+    );
+  }
+  return region;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+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 booleanField(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null;
+}
+
+function joinStringArray(value: unknown): string {
+  return Array.isArray(value)
+    ? value.filter((item) => typeof item === "string" && item.trim()).join(", ")
+    : "";
+}
+
+export function joinCountryCurrencies(value: unknown): string {
+  if (!value || typeof value !== "object") return "";
+  return Object.entries(value as Record<string, { name?: unknown }>)
+    .map(([code, info]) => {
+      const name =
+        info && typeof info.name === "string" && info.name.trim()
+          ? info.name.trim()
+          : "";
+      return name ? `${code} (${name})` : code;
+    })
+    .join(", ");
+}
+
+export function joinCountryLanguages(value: unknown): string {
+  if (!value || typeof value !== "object") return "";
+  return Object.values(value as Record<string, unknown>)
+    .filter(
+      (item): item is string =>
+        typeof item === "string" && item.trim().length > 0,
+    )
+    .join(", ");
+}
+
+export function mapCountryRow(
+  country: Record<string, unknown>,
+): Record<string, unknown> {
+  const name = (country.name ?? {}) as Record<string, unknown>;
+  const latlng = Array.isArray(country.latlng) ? country.latlng : [];
+  const cca3 = stringField(country.cca3);
+  return {
+    commonName: stringField(name.common),
+    officialName: stringField(name.official),
+    cca2: stringField(country.cca2),
+    cca3,
+    ccn3: stringField(country.ccn3),
+    capital: joinStringArray(country.capital),
+    region: stringField(country.region),
+    subregion: stringField(country.subregion),
+    population: numberField(country.population),
+    area: numberField(country.area),
+    languages: joinCountryLanguages(country.languages),
+    currencies: joinCountryCurrencies(country.currencies),
+    latitude: numberField(latlng[0]),
+    longitude: numberField(latlng[1]),
+    timezones: joinStringArray(country.timezones),
+    independent: booleanField(country.independent),
+    unMember: booleanField(country.unMember),
+    landlocked: booleanField(country.landlocked),
+    flag: stringField(country.flag),
+    url: cca3
+      ? `https://restcountries.com/v3.1/alpha/${cca3.toLowerCase()}`
+      : "",
+  };
+}
+
+export function mapCountryRows(
+  rows: Array<Record<string, unknown>>,
+  limit: number,
+): Array<Record<string, unknown>> {
+  const sorted = [...rows].sort(
+    (a, b) =>
+      (numberField(b.population) ?? 0) - (numberField(a.population) ?? 0),
+  );
+  return sorted.slice(0, limit).map((country, index) => ({
+    rank: index + 1,
+    ...mapCountryRow(country),
+  }));
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent":
+        "unicli-rest-countries (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: "rest-countries",
+  name: "country",
+  description: "Look up countries by common or official name",
+  domain: "restcountries.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "name",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Country name",
+    },
+    { name: "limit", type: "int", default: 25, description: "Max rows" },
+  ],
+  columns: COLUMNS,
+  func: async (_page, kwargs) => {
+    const name = nonEmptyString(kwargs.name, "name");
+    const limit = requireRestCountriesLimit(kwargs.limit, 25, 250);
+    const url = new URL(`${API_BASE}/name/${encodeURIComponent(name)}`);
+    url.searchParams.set("fields", COUNTRY_FIELDS);
+    const body = await fetchJson(url, "rest-countries country");
+    const rows = mapCountryRows(
+      Array.isArray(body) ? (body as Array<Record<string, unknown>>) : [],
+      limit,
+    );
+    if (rows.length === 0) {
+      throw new Error(`rest-countries country returned no rows for "${name}".`);
+    }
+    return rows;
+  },
+});
+
+cli({
+  site: "rest-countries",
+  name: "region",
+  description: "List countries in a REST Countries region",
+  domain: "restcountries.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "region",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Region name",
+    },
+    { name: "limit", type: "int", default: 250, description: "Max rows" },
+  ],
+  columns: COLUMNS,
+  func: async (_page, kwargs) => {
+    const region = requireRestCountriesRegion(kwargs.region);
+    const limit = requireRestCountriesLimit(kwargs.limit, 250, 250);
+    const url = new URL(`${API_BASE}/region/${encodeURIComponent(region)}`);
+    url.searchParams.set("fields", COUNTRY_FIELDS);
+    const body = await fetchJson(url, "rest-countries region");
+    const rows = mapCountryRows(
+      Array.isArray(body) ? (body as Array<Record<string, unknown>>) : [],
+      limit,
+    );
+    if (rows.length === 0) {
+      throw new Error(
+        `rest-countries region returned no rows for "${region}".`,
+      );
+    }
+    return rows;
+  },
+});

package/src/adapters/reuters/article-detail.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import {
+  extractReutersBody,
+  mapReutersArticleDetail,
+  requireReutersArticleUrl,
+  reutersPathFromUrl,
+} from "./article-detail.js";
+
+describe("reuters agent-facing article-detail command", () => {
+  it("validates Reuters URLs and extracts API URL paths", () => {
+    const url =
+      "https://www.reuters.com/world/us/fed-chair-says-rates-2026-05-12/?utm_source=x";
+    expect(requireReutersArticleUrl(` ${url} `)).toBe(url);
+    expect(reutersPathFromUrl(url)).toBe(
+      "/world/us/fed-chair-says-rates-2026-05-12/?utm_source=x",
+    );
+    expect(() => requireReutersArticleUrl("https://example.com/a")).toThrow(
+      "reuters.com",
+    );
+  });
+
+  it("maps article metadata and body to stable columns", () => {
+    expect(
+      mapReutersArticleDetail(
+        {
+          title: "Fed chair says rates hold",
+          display_date: "2026-05-12T01:02:03Z",
+          taxonomy: { section: { name: "Markets", path: "/markets/" } },
+          authors: [{ name: "Jane Doe" }, { byline: "John Roe" }],
+          description: { basic: "Short summary" },
+          word_count: 450,
+          canonical_url: "/markets/rates-2026-05-12/",
+          content_elements: [
+            { type: "text", content: "First paragraph." },
+            { type: "image", content: "ignored" },
+            { type: "text", content: "Second paragraph." },
+          ],
+        },
+        "https://www.reuters.com/fallback",
+      ),
+    ).toEqual({
+      title: "Fed chair says rates hold",
+      date: "2026-05-12",
+      section: "Markets",
+      section_path: "/markets/",
+      authors: "Jane Doe, John Roe",
+      description: "Short summary",
+      word_count: 450,
+      url: "https://www.reuters.com/markets/rates-2026-05-12/",
+      body: "First paragraph.\n\nSecond paragraph.",
+    });
+  });
+
+  it("extracts only text content elements", () => {
+    expect(
+      extractReutersBody({
+        content_elements: [
+          { type: "text", content: "A" },
+          { type: "raw_html", content: "<p>B</p>" },
+          { type: "text", content: "C" },
+        ],
+      }),
+    ).toBe("A\n\nC");
+  });
+});

package/src/adapters/reuters/article-detail.ts

@@ -0,0 +1,186 @@
+/**
+ * @owner   src/adapters/reuters/article-detail.ts
+ * @does    Register agent-facing Reuters article-detail using the public Fusion content API.
+ * @needs   Reuters article URLs, article-by-id-or-url-v1 envelope, robust article body extraction.
+ * @feeds   surface coverage ledger, Reuters search-to-detail workflow, article reading surfaces.
+ * @breaks  Reuters API query shape drift or content element changes can hide article bodies.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const REUTERS_API =
+  "https://www.reuters.com/pf/api/v3/content/fetch/article-by-id-or-url-v1";
+const REUTERS_HOST = /^https?:\/\/(?:www\.)?reuters\.com\//i;
+
+interface ReutersAuthor {
+  name?: unknown;
+  byline?: unknown;
+}
+
+interface ReutersContentElement {
+  type?: unknown;
+  content?: unknown;
+}
+
+interface ReutersArticle {
+  title?: unknown;
+  headlines?: { basic?: unknown };
+  display_date?: unknown;
+  published_time?: unknown;
+  taxonomy?: {
+    section?: {
+      name?: unknown;
+      path?: unknown;
+    };
+  };
+  authors?: unknown;
+  description?: { basic?: unknown };
+  subheadlines?: { basic?: unknown };
+  word_count?: unknown;
+  canonical_url?: unknown;
+  content_elements?: unknown;
+}
+
+interface ReutersEnvelope {
+  result?: ReutersArticle;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function dateOnly(value: unknown): string {
+  return stringField(value).split("T")[0] ?? "";
+}
+
+function absoluteReutersUrl(value: unknown, fallback: string): string {
+  const raw = stringField(value);
+  if (!raw) return fallback;
+  return /^https?:\/\//i.test(raw) ? raw : `https://www.reuters.com${raw}`;
+}
+
+function authorNames(value: unknown): string {
+  if (!Array.isArray(value)) return "";
+  return value
+    .map((author: ReutersAuthor | string) => {
+      return typeof author === "string"
+        ? author
+        : stringField(author.name) || stringField(author.byline);
+    })
+    .map((name) => name.trim())
+    .filter(Boolean)
+    .join(", ");
+}
+
+export function requireReutersArticleUrl(value: unknown): string {
+  const url = String(value ?? "").trim();
+  if (!url) throw new Error("Reuters article URL cannot be empty.");
+  if (!REUTERS_HOST.test(url)) {
+    throw new Error(`Reuters article URL must be on reuters.com: ${url}`);
+  }
+  return url;
+}
+
+export function reutersPathFromUrl(url: string): string {
+  const parsed = new URL(url);
+  return `${parsed.pathname}${parsed.search}` || "/";
+}
+
+export function extractReutersBody(article: ReutersArticle): string {
+  const elements = Array.isArray(article.content_elements)
+    ? article.content_elements
+    : [];
+  return elements
+    .filter((element): element is ReutersContentElement => {
+      return typeof element === "object" && element !== null;
+    })
+    .filter((element) => element.type === "text")
+    .map((element) => stringField(element.content))
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function mapReutersArticleDetail(
+  article: ReutersArticle | undefined,
+  fallbackUrl: string,
+): Record<string, unknown> {
+  if (!article) throw new Error("Reuters article-detail returned no result.");
+  const body = extractReutersBody(article);
+  const title =
+    stringField(article.title) || stringField(article.headlines?.basic);
+  if (!title && !body) {
+    throw new Error("Reuters article-detail returned no article body.");
+  }
+  return {
+    title,
+    date: dateOnly(article.display_date || article.published_time),
+    section: stringField(article.taxonomy?.section?.name),
+    section_path: stringField(article.taxonomy?.section?.path),
+    authors: authorNames(article.authors),
+    description:
+      stringField(article.description?.basic) ||
+      stringField(article.subheadlines?.basic),
+    word_count:
+      typeof article.word_count === "number" &&
+      Number.isFinite(article.word_count)
+        ? article.word_count
+        : null,
+    url: absoluteReutersUrl(article.canonical_url, fallbackUrl),
+    body,
+  };
+}
+
+async function fetchReutersArticle(url: string): Promise<ReutersArticle> {
+  const query = JSON.stringify({
+    url: reutersPathFromUrl(url),
+    website: "reuters",
+  });
+  const apiUrl = new URL(REUTERS_API);
+  apiUrl.searchParams.set("query", query);
+  const response = await fetch(apiUrl, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": "Mozilla/5.0 (compatible; Uni-CLI)",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Reuters article-detail returned HTTP ${response.status}.`);
+  }
+  const envelope = (await response.json()) as ReutersEnvelope;
+  if (!envelope.result)
+    throw new Error("Reuters article-detail returned no result.");
+  return envelope.result;
+}
+
+cli({
+  site: "reuters",
+  name: "article-detail",
+  description: "Reuters article detail with title, metadata, and body text",
+  domain: "www.reuters.com",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    {
+      name: "url",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Reuters article URL",
+    },
+  ],
+  columns: [
+    "title",
+    "date",
+    "section",
+    "section_path",
+    "authors",
+    "description",
+    "word_count",
+    "url",
+    "body",
+  ],
+  func: async (_page, kwargs) => {
+    const url = requireReutersArticleUrl(kwargs.url);
+    return [mapReutersArticleDetail(await fetchReutersArticle(url), url)];
+  },
+});

package/src/adapters/rfc/rfc.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { mapRfcRow, requireRfcNumber, trimRfcDate } from "./rfc.js";
+
+describe("rfc agent-facing metadata command", () => {
+  it("validates RFC numbers", () => {
+    expect(requireRfcNumber("rfc9000")).toBe(9000);
+    expect(requireRfcNumber(791)).toBe(791);
+    expect(() => requireRfcNumber("9000bis")).toThrow("not valid");
+  });
+
+  it("normalizes RFC dates", () => {
+    expect(trimRfcDate("2022-02-19 08:46:51")).toBe("2022-02-19");
+    expect(trimRfcDate("no date")).toBeNull();
+  });
+
+  it("maps RFC metadata rows", () => {
+    expect(
+      mapRfcRow(9000, {
+        title: "QUIC: A UDP-Based Multiplexed and Secure Transport",
+        state: "RFC",
+        std_level: "Proposed Standard",
+        group: { name: "QUIC", type: "wg" },
+        pages: "151",
+        time: "2021-05-27T00:00:00+00:00",
+        authors: [{ name: "J. Iyengar" }, { name: "M. Thomson" }],
+        abstract: "This document defines the core of QUIC.",
+      }),
+    ).toMatchObject({
+      rfc: 9000,
+      group: "QUIC",
+      pages: 151,
+      published: "2021-05-27",
+      authors: "J. Iyengar, M. Thomson",
+      rfcEditorUrl: "https://www.rfc-editor.org/rfc/rfc9000",
+    });
+  });
+});