@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/wikidata/entities.ts

@@ -0,0 +1,253 @@
+/**
+ * @owner   src/adapters/wikidata/entities.ts
+ * @does    Register agent-facing Wikidata entity search and detail commands.
+ * @needs   Wikidata public APIs, language validation, Q/P/L entity id validation.
+ * @feeds   surface coverage ledger, Wikidata search rows, entity summary rows.
+ * @breaks  Wikidata API drift, weak id validation, or silent empty rows hide entity lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://www.wikidata.org";
+const ENTITY_ID_RE = /^[QPL]\d+$/;
+
+function requireNonEmpty(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`wikidata ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireWikidataLimit(value: unknown): number {
+  const raw =
+    value === undefined || value === null || value === "" ? 20 : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+    throw new Error("wikidata limit must be an integer in [1, 50].");
+  }
+  return limit;
+}
+
+export function requireWikidataLanguage(value: unknown): string {
+  const language = String(value ?? "en")
+    .trim()
+    .toLowerCase();
+  if (!/^[a-z]{2,3}(-[a-z]{2,8})?$/.test(language)) {
+    throw new Error(`wikidata language "${String(value)}" is not valid.`);
+  }
+  return language;
+}
+
+export function requireWikidataEntityId(value: unknown): string {
+  const raw = String(value ?? "")
+    .trim()
+    .toUpperCase();
+  if (!raw) throw new Error("wikidata entity id cannot be empty.");
+  const id = raw.replace(/^HTTPS?:\/\/[^/]+\/WIKI\//i, "");
+  if (!ENTITY_ID_RE.test(id)) {
+    throw new Error(`wikidata entity id "${String(value)}" is not valid.`);
+  }
+  return id;
+}
+
+function objectField(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function pickLocalizedValue(
+  map: unknown,
+  language: string,
+): string | null {
+  const values = objectField(map);
+  const direct = objectField(values[language]);
+  if (stringField(direct.value)) return stringField(direct.value);
+  const english = objectField(values.en);
+  return stringField(english.value) || null;
+}
+
+export function joinLocalizedAliases(
+  value: unknown,
+  language: string,
+  max = 5,
+): string {
+  const aliases = objectField(value);
+  const direct = Array.isArray(aliases[language]) ? aliases[language] : [];
+  const fallback = Array.isArray(aliases.en) ? aliases.en : [];
+  const list = direct.length > 0 ? direct : fallback;
+  const names = list
+    .map((item) => stringField(objectField(item).value))
+    .filter(Boolean);
+  return names.length > max
+    ? [...names.slice(0, max), `(+${names.length - max})`].join(", ")
+    : names.join(", ");
+}
+
+export function mapWikidataSearchRows(
+  rows: Array<Record<string, unknown>>,
+  limit: number,
+): Array<Record<string, unknown>> {
+  return rows.slice(0, limit).map((row, index) => {
+    const qid = stringField(row.id);
+    const match = objectField(row.match);
+    return {
+      rank: index + 1,
+      qid,
+      label: stringField(row.label),
+      description: stringField(row.description),
+      matchType: stringField(match.type),
+      matchText: stringField(match.text),
+      url: qid ? `${API_BASE}/wiki/${qid}` : "",
+    };
+  });
+}
+
+export function mapWikidataEntityRow(
+  id: string,
+  entity: Record<string, unknown>,
+  language: string,
+): Record<string, unknown> {
+  const claims = objectField(entity.claims);
+  const sitelinks = objectField(entity.sitelinks);
+  const enwiki = objectField(sitelinks.enwiki);
+  return {
+    qid: id,
+    type: stringField(entity.type),
+    label: pickLocalizedValue(entity.labels, language),
+    description: pickLocalizedValue(entity.descriptions, language),
+    aliases: joinLocalizedAliases(entity.aliases, language),
+    claimPropertyCount: Object.keys(claims).length,
+    sitelinkCount: Object.keys(sitelinks).length,
+    enwikiTitle: stringField(enwiki.title) || null,
+    modified: stringField(entity.modified) || null,
+    url: `${API_BASE}/wiki/${id}`,
+  };
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-wikidata (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: "wikidata",
+  name: "search",
+  description: "Search Wikidata items by keyword",
+  domain: "www.wikidata.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Search keyword",
+    },
+    {
+      name: "language",
+      type: "str",
+      default: "en",
+      description: "Language code",
+    },
+    { name: "limit", type: "int", default: 20, description: "Max rows" },
+  ],
+  columns: [
+    "rank",
+    "qid",
+    "label",
+    "description",
+    "matchType",
+    "matchText",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const query = requireNonEmpty(kwargs.query, "query");
+    const language = requireWikidataLanguage(kwargs.language);
+    const limit = requireWikidataLimit(kwargs.limit);
+    const url = new URL(`${API_BASE}/w/api.php`);
+    url.searchParams.set("action", "wbsearchentities");
+    url.searchParams.set("search", query);
+    url.searchParams.set("language", language);
+    url.searchParams.set("uselang", language);
+    url.searchParams.set("type", "item");
+    url.searchParams.set("format", "json");
+    url.searchParams.set("limit", String(limit));
+    url.searchParams.set("origin", "*");
+    const body = (await fetchJson(url, "wikidata search")) as {
+      search?: unknown;
+    };
+    const rows = mapWikidataSearchRows(
+      Array.isArray(body.search)
+        ? (body.search as Array<Record<string, unknown>>)
+        : [],
+      limit,
+    );
+    if (rows.length === 0) {
+      throw new Error(`wikidata search returned no rows for "${query}".`);
+    }
+    return rows;
+  },
+});
+
+cli({
+  site: "wikidata",
+  name: "entity",
+  description: "Fetch a Wikidata entity by Q/P/L id",
+  domain: "www.wikidata.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Entity id",
+    },
+    {
+      name: "language",
+      type: "str",
+      default: "en",
+      description: "Language code",
+    },
+  ],
+  columns: [
+    "qid",
+    "type",
+    "label",
+    "description",
+    "aliases",
+    "claimPropertyCount",
+    "sitelinkCount",
+    "enwikiTitle",
+    "modified",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireWikidataEntityId(kwargs.id);
+    const language = requireWikidataLanguage(kwargs.language);
+    const body = objectField(
+      await fetchJson(
+        `${API_BASE}/wiki/Special:EntityData/${encodeURIComponent(id)}.json`,
+        "wikidata entity",
+      ),
+    );
+    const entity = objectField(objectField(body.entities)[id]);
+    if (!entity.id && !entity.type) {
+      throw new Error(`wikidata entity returned no row for "${id}".`);
+    }
+    return [mapWikidataEntityRow(id, entity, language)];
+  },
+});

package/src/adapters/wikipedia/page.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapWikipediaPageRow,
+  requireParagraphCap,
+  requireWikiLang,
+  requireWikiTitle,
+} from "./page.js";
+
+describe("wikipedia agent-facing page command", () => {
+  it("validates title, language, and paragraph cap", () => {
+    expect(requireWikiTitle(" Transformer ")).toBe("Transformer");
+    expect(() => requireWikiTitle("")).toThrow("cannot be empty");
+    expect(requireWikiLang("ZH-Hans")).toBe("zh-hans");
+    expect(() => requireWikiLang("english")).toThrow("language code");
+    expect(requireParagraphCap(undefined)).toBe(0);
+    expect(requireParagraphCap("2")).toBe(2);
+    expect(() => requireParagraphCap("-1")).toThrow("non-negative");
+  });
+
+  it("maps full extract with optional paragraph cap", () => {
+    expect(
+      mapWikipediaPageRow(
+        {
+          title: "Transformer",
+          description: "ML model",
+          pageid: 123,
+          extract: "Para one.\n\nPara two.\n\nPara three.",
+          fullurl: "https://en.wikipedia.org/wiki/Transformer",
+        },
+        "en",
+        "Transformer",
+        2,
+      ),
+    ).toEqual({
+      title: "Transformer",
+      description: "ML model",
+      pageId: 123,
+      paragraphs: 2,
+      extract: "Para one.\n\nPara two.",
+      url: "https://en.wikipedia.org/wiki/Transformer",
+    });
+    expect(() =>
+      mapWikipediaPageRow({ missing: true }, "en", "Missing", 0),
+    ).toThrow("No Wikipedia article");
+    expect(() =>
+      mapWikipediaPageRow({ title: "Empty", extract: "" }, "en", "Empty", 0),
+    ).toThrow("no plain-text extract");
+  });
+});

package/src/adapters/wikipedia/page.ts

@@ -0,0 +1,158 @@
+/**
+ * @owner   src/adapters/wikipedia/page.ts
+ * @does    Register agent-facing full Wikipedia page extract command.
+ * @needs   MediaWiki Action API, language validation, explicit paragraph caps.
+ * @feeds   surface coverage ledger, encyclopedia article reading workflow.
+ * @breaks  MediaWiki envelope drift or silent extract truncation hides article content.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+interface WikiPage {
+  title?: unknown;
+  description?: unknown;
+  pageid?: unknown;
+  extract?: unknown;
+  fullurl?: unknown;
+  missing?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+export function requireWikiTitle(value: unknown): string {
+  const title = String(value ?? "").trim();
+  if (!title) throw new Error("wikipedia page title cannot be empty.");
+  return title;
+}
+
+export function requireWikiLang(value: unknown): string {
+  const lang = String(value ?? "en")
+    .trim()
+    .toLowerCase();
+  if (!/^[a-z]{2,3}(?:-[a-z0-9]+)?$/.test(lang)) {
+    throw new Error(
+      `wikipedia lang must be a language code, got "${String(value)}".`,
+    );
+  }
+  return lang;
+}
+
+export function requireParagraphCap(value: unknown): number {
+  if (value === undefined || value === null || value === "") return 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error("paragraphs must be a non-negative integer.");
+  }
+  return n;
+}
+
+export function mapWikipediaPageRow(
+  page: WikiPage | undefined,
+  lang: string,
+  requestedTitle: string,
+  paragraphCap: number,
+): Record<string, unknown> {
+  if (!page || page.missing) {
+    throw new Error(
+      `No Wikipedia article "${requestedTitle}" on ${lang}.wikipedia.org.`,
+    );
+  }
+  const fullExtract = stringField(page.extract);
+  if (!fullExtract.trim()) {
+    throw new Error(
+      `Wikipedia article "${stringField(page.title) || requestedTitle}" has no plain-text extract.`,
+    );
+  }
+  const paragraphs = fullExtract
+    .split(/\n{2,}/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  const selected =
+    paragraphCap > 0 ? paragraphs.slice(0, paragraphCap) : paragraphs;
+  const title = stringField(page.title) || requestedTitle;
+  return {
+    title,
+    description: stringField(page.description),
+    pageId: page.pageid ?? null,
+    paragraphs: selected.length,
+    extract: selected.join("\n\n"),
+    url:
+      stringField(page.fullurl) ||
+      `https://${lang}.wikipedia.org/wiki/${encodeURIComponent(title.replace(/ /g, "_"))}`,
+  };
+}
+
+async function fetchWikipediaPage(
+  lang: string,
+  title: string,
+): Promise<WikiPage> {
+  const url = new URL(`https://${lang}.wikipedia.org/w/api.php`);
+  url.searchParams.set("action", "query");
+  url.searchParams.set("format", "json");
+  url.searchParams.set("formatversion", "2");
+  url.searchParams.set("prop", "extracts|info|description");
+  url.searchParams.set("inprop", "url");
+  url.searchParams.set("explaintext", "1");
+  url.searchParams.set("redirects", "1");
+  url.searchParams.set("titles", title);
+
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent":
+        "unicli-wikipedia/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (!response.ok)
+    throw new Error(`wikipedia page returned HTTP ${response.status}.`);
+  const data = (await response.json()) as {
+    error?: { code?: unknown; info?: unknown };
+    query?: { pages?: WikiPage[] };
+  };
+  if (data.error) {
+    throw new Error(
+      `wikipedia API error: ${stringField(data.error.info) || stringField(data.error.code)}`,
+    );
+  }
+  return Array.isArray(data.query?.pages) ? data.query.pages[0] : {};
+}
+
+cli({
+  site: "wikipedia",
+  name: "page",
+  description: "Full plain-text extract of a Wikipedia article",
+  domain: "wikipedia.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "title",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Article title",
+    },
+    { name: "lang", type: "str", default: "en", description: "Language code" },
+    {
+      name: "paragraphs",
+      type: "int",
+      default: 0,
+      description: "Paragraph cap, 0 means full",
+    },
+  ],
+  columns: ["title", "description", "pageId", "paragraphs", "extract", "url"],
+  func: async (_page, kwargs) => {
+    const title = requireWikiTitle(kwargs.title);
+    const lang = requireWikiLang(kwargs.lang);
+    const paragraphCap = requireParagraphCap(kwargs.paragraphs);
+    return [
+      mapWikipediaPageRow(
+        await fetchWikipediaPage(lang, title),
+        lang,
+        title,
+        paragraphCap,
+      ),
+    ];
+  },
+});

package/src/adapters/wttr/weather.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapCurrentWeatherRow,
+  mapForecastRows,
+  pickWeatherDescription,
+  requireWttrDays,
+} from "./weather.js";
+
+describe("wttr agent-facing weather commands", () => {
+  it("validates forecast days", () => {
+    expect(requireWttrDays(undefined)).toBe(3);
+    expect(requireWttrDays("2")).toBe(2);
+    expect(() => requireWttrDays("4")).toThrow("wttr days must");
+  });
+
+  it("picks wttr description arrays", () => {
+    expect(pickWeatherDescription([{ value: " Sunny " }])).toBe("Sunny");
+    expect(pickWeatherDescription([])).toBe("");
+  });
+
+  it("maps current weather rows", () => {
+    expect(
+      mapCurrentWeatherRow(
+        {
+          nearest_area: [
+            {
+              areaName: [{ value: "Tokyo" }],
+              region: [{ value: "Tokyo" }],
+              country: [{ value: "Japan" }],
+              latitude: "35.68",
+              longitude: "139.76",
+            },
+          ],
+          current_condition: [
+            {
+              localObsDateTime: "2026-05-12 17:00",
+              temp_C: "21",
+              temp_F: "70",
+              FeelsLikeC: "20",
+              weatherDesc: [{ value: "Partly cloudy" }],
+              humidity: "55",
+              windspeedKmph: "9",
+              winddir16Point: "NE",
+            },
+          ],
+        },
+        "tokyo",
+      ),
+    ).toMatchObject({
+      location: "Tokyo",
+      country: "Japan",
+      tempC: 21,
+      tempF: 70,
+      description: "Partly cloudy",
+      humidity: 55,
+      windDirection: "NE",
+    });
+    expect(() => mapCurrentWeatherRow({}, "nowhere")).toThrow("no conditions");
+  });
+
+  it("maps forecast rows using noon description and astronomy", () => {
+    expect(
+      mapForecastRows(
+        {
+          weather: [
+            {
+              date: "2026-05-12",
+              mintempC: "10",
+              maxtempC: "22",
+              avgtempC: "16",
+              sunHour: "11.5",
+              totalSnow_cm: "0",
+              uvIndex: "5",
+              astronomy: [{ sunrise: "05:00 AM", sunset: "06:30 PM" }],
+              hourly: [
+                { weatherDesc: [{ value: "Morning" }] },
+                {},
+                {},
+                {},
+                { weatherDesc: [{ value: "Clear" }] },
+              ],
+            },
+          ],
+        },
+        1,
+        "tokyo",
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        date: "2026-05-12",
+        minTempC: 10,
+        maxTempC: 22,
+        description: "Clear",
+        sunrise: "05:00 AM",
+      },
+    ]);
+  });
+});