@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/oeis/sequences.ts

@@ -0,0 +1,234 @@
+/**
+ * @owner   src/adapters/oeis/sequences.ts
+ * @does    Register agent-facing OEIS sequence search and detail commands.
+ * @needs   OEIS public JSON search endpoint, bounded pagination, sequence id validation.
+ * @feeds   surface coverage ledger, integer sequence search rows, OEIS detail summaries.
+ * @breaks  OEIS API drift, weak A-number parsing, or silent empty rows hide sequence lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://oeis.org";
+const SEQUENCE_ID_RE = /^A\d{1,7}$/;
+
+function requireNonEmpty(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`oeis ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireOeisLimit(value: unknown): number {
+  const raw =
+    value === undefined || value === null || value === "" ? 10 : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error("oeis limit must be an integer in [1, 100].");
+  }
+  return limit;
+}
+
+export function requireOeisSequenceId(value: unknown): string {
+  const raw = String(value ?? "")
+    .trim()
+    .toUpperCase();
+  if (!raw) throw new Error("oeis sequence id cannot be empty.");
+  const id = raw
+    .replace(/^HTTPS?:\/\/(?:WWW\.)?OEIS\.ORG\//i, "")
+    .replace(/\/.*$/, "");
+  if (!SEQUENCE_ID_RE.test(id)) {
+    throw new Error(
+      `oeis sequence id "${String(value)}" is not a valid A-number.`,
+    );
+  }
+  return id;
+}
+
+export function formatOeisId(value: unknown): string {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) return "";
+  return `A${String(number).padStart(6, "0")}`;
+}
+
+export function previewOeisTerms(value: unknown, max = 12): string {
+  if (typeof value !== "string") return "";
+  const terms = value
+    .split(",")
+    .map((term) => term.trim())
+    .filter(Boolean);
+  return terms.length > max
+    ? [...terms.slice(0, max), `(+${terms.length - max})`].join(", ")
+    : terms.join(", ");
+}
+
+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 countArray(value: unknown): number {
+  return Array.isArray(value) ? value.length : 0;
+}
+
+export function mapOeisSearchRows(
+  rows: Array<Record<string, unknown>>,
+): Array<Record<string, unknown>> {
+  return rows.map((row, index) => {
+    const id = formatOeisId(row.number);
+    return {
+      rank: index + 1,
+      id,
+      name: stringField(row.name),
+      keywords: stringField(row.keyword),
+      preview: previewOeisTerms(row.data),
+      author: stringField(row.author),
+      created: stringField(row.created),
+      url: id ? `${API_BASE}/${id}` : "",
+    };
+  });
+}
+
+export function mapOeisSequenceRow(
+  row: Record<string, unknown>,
+  fallbackId: string,
+): Record<string, unknown> {
+  const id = formatOeisId(row.number) || fallbackId;
+  const data = stringField(row.data);
+  const termCount = data ? data.split(",").filter(Boolean).length : 0;
+  return {
+    id,
+    name: stringField(row.name),
+    keywords: stringField(row.keyword),
+    preview: previewOeisTerms(data),
+    termCount,
+    offset: stringField(row.offset),
+    author: stringField(row.author),
+    created: stringField(row.created),
+    revision: numberField(row.revision),
+    commentCount: countArray(row.comment),
+    formulaCount: countArray(row.formula),
+    referenceCount: countArray(row.reference),
+    xrefCount: countArray(row.xref),
+    linkCount: countArray(row.link),
+    url: `${API_BASE}/${id}`,
+  };
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-oeis (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: "oeis",
+  name: "search",
+  description: "Search OEIS sequences by keyword or numeric pattern",
+  domain: "oeis.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Keyword or comma-separated terms",
+    },
+    { name: "limit", type: "int", default: 10, description: "Max rows" },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "name",
+    "keywords",
+    "preview",
+    "author",
+    "created",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const query = requireNonEmpty(kwargs.query, "query");
+    const limit = requireOeisLimit(kwargs.limit);
+    const collected: Array<Record<string, unknown>> = [];
+    for (let start = 0; collected.length < limit; start += 10) {
+      const url = new URL(`${API_BASE}/search`);
+      url.searchParams.set("q", query);
+      url.searchParams.set("fmt", "json");
+      url.searchParams.set("start", String(start));
+      const body = await fetchJson(url, "oeis search");
+      const page = Array.isArray(body)
+        ? (body as Array<Record<string, unknown>>)
+        : [];
+      if (page.length === 0) break;
+      collected.push(...page.slice(0, limit - collected.length));
+      if (page.length < 10) break;
+    }
+    const rows = mapOeisSearchRows(collected);
+    if (rows.length === 0)
+      throw new Error(`oeis search returned no rows for "${query}".`);
+    return rows;
+  },
+});
+
+cli({
+  site: "oeis",
+  name: "sequence",
+  description: "Fetch OEIS sequence detail by A-number",
+  domain: "oeis.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "OEIS A-number",
+    },
+  ],
+  columns: [
+    "id",
+    "name",
+    "keywords",
+    "preview",
+    "termCount",
+    "offset",
+    "author",
+    "created",
+    "revision",
+    "commentCount",
+    "formulaCount",
+    "referenceCount",
+    "xrefCount",
+    "linkCount",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireOeisSequenceId(kwargs.id);
+    const url = new URL(`${API_BASE}/search`);
+    url.searchParams.set("q", `id:${id}`);
+    url.searchParams.set("fmt", "json");
+    const body = await fetchJson(url, "oeis sequence");
+    const list = Array.isArray(body)
+      ? (body as Array<Record<string, unknown>>)
+      : [];
+    if (list.length === 0)
+      throw new Error(`oeis sequence returned no row for "${id}".`);
+    return [mapOeisSequenceRow(list[0] ?? {}, id)];
+  },
+});

package/src/adapters/openalex/works.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapOpenAlexSearchRows,
+  mapOpenAlexWorkRow,
+  reconstructOpenAlexAbstract,
+  requireOpenAlexLimit,
+  requireOpenAlexString,
+  requireOpenAlexWorkRef,
+} from "./works.js";
+
+describe("openalex agent-facing commands", () => {
+  it("validates search and work refs", () => {
+    expect(requireOpenAlexString(" transformers ", "query")).toBe(
+      "transformers",
+    );
+    expect(() => requireOpenAlexString("", "query")).toThrow("cannot be empty");
+    expect(requireOpenAlexLimit(undefined)).toBe(20);
+    expect(requireOpenAlexLimit("200")).toBe(200);
+    expect(() => requireOpenAlexLimit("0")).toThrow("openalex limit must");
+    expect(requireOpenAlexWorkRef("w2741809807")).toBe("W2741809807");
+    expect(requireOpenAlexWorkRef("https://doi.org/10.7717/peerj.4375")).toBe(
+      "doi:10.7717/peerj.4375",
+    );
+    expect(() => requireOpenAlexWorkRef("A12345")).toThrow("not recognised");
+  });
+
+  it("reconstructs OpenAlex abstracts from inverted indexes", () => {
+    expect(reconstructOpenAlexAbstract({ world: [1], hello: [0] })).toBe(
+      "hello world",
+    );
+  });
+
+  it("maps search rows", () => {
+    expect(
+      mapOpenAlexSearchRows(
+        [
+          {
+            id: "https://openalex.org/W1234",
+            doi: "https://doi.org/10.1/example",
+            title: "A paper",
+            publication_year: 2026,
+            cited_by_count: 5,
+            authorships: [{ author: { display_name: "Ada" } }],
+            primary_location: { source: { display_name: "Journal" } },
+            open_access: { is_oa: true },
+            type: "article",
+          },
+        ],
+        20,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        id: "W1234",
+        title: "A paper",
+        year: 2026,
+        citations: 5,
+        firstAuthor: "Ada",
+        venue: "Journal",
+        openAccess: true,
+        type: "article",
+        doi: "10.1/example",
+        url: "https://openalex.org/W1234",
+      },
+    ]);
+  });
+
+  it("maps work detail rows", () => {
+    expect(
+      mapOpenAlexWorkRow({
+        id: "https://openalex.org/W1234",
+        title: "A paper",
+        type: "article",
+        publication_year: 2026,
+        publication_date: "2026-05-01",
+        language: "en",
+        authorships: [
+          { author: { display_name: "Ada" } },
+          { author: { display_name: "Grace" } },
+        ],
+        primary_location: { source: { display_name: "Journal" } },
+        cited_by_count: 5,
+        open_access: { is_oa: true, oa_url: "https://example.test/pdf" },
+        referenced_works: ["W1", "W2"],
+        doi: "https://doi.org/10.1/example",
+        abstract_inverted_index: { hello: [0], world: [1] },
+      }),
+    ).toMatchObject({
+      id: "W1234",
+      authors: "Ada, Grace",
+      referencedCount: 2,
+      doi: "10.1/example",
+      abstract: "hello world",
+    });
+    expect(() => mapOpenAlexWorkRow({})).toThrow(
+      "OpenAlex returned no work record",
+    );
+  });
+});

package/src/adapters/openalex/works.ts

@@ -0,0 +1,319 @@
+/**
+ * @owner   src/adapters/openalex/works.ts
+ * @does    Register agent-facing OpenAlex work search and detail commands.
+ * @needs   Public OpenAlex API, TypeScript adapter loader, work id/DOI normalization.
+ * @feeds   surface coverage ledger, scholarly work command surface, agent-readable OpenAlex rows.
+ * @breaks  OpenAlex API envelope drift, weak DOI/id parsing, or abstract reconstruction errors degrade research lookup.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const OPENALEX_BASE = "https://api.openalex.org";
+const WORK_ID_RE = /^W\d{4,}$/;
+const DOI_RE = /^10\.\S+$/;
+const SEARCH_SELECT = [
+  "id",
+  "doi",
+  "title",
+  "publication_year",
+  "cited_by_count",
+  "authorships",
+  "primary_location",
+  "open_access",
+  "type",
+].join(",");
+const WORK_SELECT = [
+  "id",
+  "doi",
+  "title",
+  "publication_year",
+  "publication_date",
+  "cited_by_count",
+  "authorships",
+  "primary_location",
+  "open_access",
+  "type",
+  "referenced_works",
+  "language",
+  "abstract_inverted_index",
+].join(",");
+
+interface OpenAlexWork {
+  id?: unknown;
+  doi?: unknown;
+  title?: unknown;
+  publication_year?: unknown;
+  publication_date?: unknown;
+  cited_by_count?: unknown;
+  authorships?: Array<{
+    author?: {
+      display_name?: unknown;
+    };
+  }>;
+  primary_location?: {
+    source?: {
+      display_name?: unknown;
+    };
+  };
+  open_access?: {
+    is_oa?: unknown;
+    oa_url?: unknown;
+  };
+  type?: unknown;
+  referenced_works?: unknown[];
+  language?: unknown;
+  abstract_inverted_index?: Record<string, number[]>;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function requireOpenAlexString(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`openalex ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireOpenAlexLimit(value: unknown, fallback = 20): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 200) {
+    throw new Error(
+      `openalex limit must be an integer in [1, 200]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+export function bareOpenAlexId(value: unknown): string {
+  return stringField(value)
+    .trim()
+    .replace(/^https?:\/\/(?:api\.)?openalex\.org\//i, "")
+    .replace(/^works\//i, "");
+}
+
+export function bareDoi(value: unknown): string {
+  return stringField(value)
+    .trim()
+    .replace(/^https?:\/\/(?:dx\.)?doi\.org\//i, "");
+}
+
+export function requireOpenAlexWorkRef(value: unknown): string {
+  const raw = String(value ?? "").trim();
+  if (!raw) throw new Error("openalex work id is required.");
+  const openAlexUrl = raw.match(
+    /^https?:\/\/(?:api\.)?openalex\.org\/(?:works\/)?([A-Za-z]\d+)/i,
+  );
+  if (openAlexUrl) {
+    const id = openAlexUrl[1].toUpperCase();
+    if (!id.startsWith("W"))
+      throw new Error(`openalex id must be a Work id, got ${id}.`);
+    return id;
+  }
+  const upper = raw.toUpperCase();
+  if (WORK_ID_RE.test(upper)) return upper;
+  if (/^doi:/i.test(raw)) {
+    const doi = raw.replace(/^doi:/i, "").trim();
+    if (DOI_RE.test(doi)) return `doi:${doi}`;
+  }
+  const doiUrl = raw.match(/^https?:\/\/(?:dx\.)?doi\.org\/(.+)$/i);
+  if (doiUrl && DOI_RE.test(doiUrl[1])) return `doi:${doiUrl[1]}`;
+  if (DOI_RE.test(raw)) return `doi:${raw}`;
+  throw new Error(`openalex work id "${raw}" is not recognised.`);
+}
+
+export function reconstructOpenAlexAbstract(index: unknown): string {
+  if (!index || typeof index !== "object") return "";
+  const positions: string[] = [];
+  for (const [token, values] of Object.entries(
+    index as Record<string, unknown>,
+  )) {
+    if (!Array.isArray(values)) continue;
+    for (const pos of values) {
+      if (Number.isInteger(pos) && pos >= 0 && pos < 100_000) {
+        positions[pos] = token;
+      }
+    }
+  }
+  return positions.filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+}
+
+function appendMailto(url: string): string {
+  const mailto = process.env.OPENALEX_MAILTO?.trim();
+  if (!mailto) return url;
+  return `${url}${url.includes("?") ? "&" : "?"}mailto=${encodeURIComponent(mailto)}`;
+}
+
+function firstAuthor(work: OpenAlexWork): string {
+  return Array.isArray(work.authorships) && work.authorships.length > 0
+    ? stringField(work.authorships[0]?.author?.display_name).trim()
+    : "";
+}
+
+function authors(work: OpenAlexWork): string {
+  return Array.isArray(work.authorships)
+    ? work.authorships
+        .map((item) => stringField(item.author?.display_name).trim())
+        .filter(Boolean)
+        .join(", ")
+    : "";
+}
+
+function venue(work: OpenAlexWork): string {
+  return stringField(work.primary_location?.source?.display_name).trim();
+}
+
+export function mapOpenAlexSearchRows(
+  works: OpenAlexWork[],
+  limit: number,
+): Array<Record<string, unknown>> {
+  return works.slice(0, limit).map((work, index) => {
+    const id = bareOpenAlexId(work.id);
+    return {
+      rank: index + 1,
+      id,
+      title: stringField(work.title).trim(),
+      year: numberField(work.publication_year),
+      citations: numberField(work.cited_by_count),
+      firstAuthor: firstAuthor(work),
+      venue: venue(work),
+      openAccess: Boolean(work.open_access?.is_oa),
+      type: stringField(work.type).trim(),
+      doi: bareDoi(work.doi),
+      url: id ? `https://openalex.org/${id}` : "",
+    };
+  });
+}
+
+export function mapOpenAlexWorkRow(
+  work: OpenAlexWork,
+): Record<string, unknown> {
+  const id = bareOpenAlexId(work.id);
+  if (!id) throw new Error("OpenAlex returned no work record.");
+  return {
+    id,
+    title: stringField(work.title).trim(),
+    type: stringField(work.type).trim(),
+    year: numberField(work.publication_year),
+    date: stringField(work.publication_date).trim(),
+    language: stringField(work.language).trim(),
+    authors: authors(work),
+    venue: venue(work),
+    citations: numberField(work.cited_by_count),
+    openAccess: Boolean(work.open_access?.is_oa),
+    openAccessUrl: stringField(work.open_access?.oa_url).trim(),
+    referencedCount: Array.isArray(work.referenced_works)
+      ? work.referenced_works.length
+      : null,
+    doi: bareDoi(work.doi),
+    abstract: reconstructOpenAlexAbstract(work.abstract_inverted_index),
+    url: `https://openalex.org/${id}`,
+  };
+}
+
+async function fetchOpenAlex(url: string, label: string): Promise<unknown> {
+  const response = await fetch(appendMailto(url), {
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  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: "openalex",
+  name: "search",
+  description: "Search OpenAlex Works by keyword",
+  domain: "api.openalex.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Search text",
+    },
+    { name: "limit", type: "int", default: 20, description: "Max works" },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "title",
+    "year",
+    "citations",
+    "firstAuthor",
+    "venue",
+    "openAccess",
+    "type",
+    "doi",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const query = requireOpenAlexString(kwargs.query, "query");
+    const limit = requireOpenAlexLimit(kwargs.limit);
+    const body = (await fetchOpenAlex(
+      `${OPENALEX_BASE}/works?search=${encodeURIComponent(query)}&per-page=${limit}&select=${SEARCH_SELECT}`,
+      "openalex search",
+    )) as { results?: OpenAlexWork[] };
+    const rows = mapOpenAlexSearchRows(
+      Array.isArray(body.results) ? body.results : [],
+      limit,
+    );
+    if (rows.length === 0)
+      throw new Error(`No OpenAlex works matched "${query}".`);
+    return rows;
+  },
+});
+
+cli({
+  site: "openalex",
+  name: "work",
+  description: "Fetch a single OpenAlex Work",
+  domain: "api.openalex.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "OpenAlex Work id or DOI",
+    },
+  ],
+  columns: [
+    "id",
+    "title",
+    "type",
+    "year",
+    "date",
+    "language",
+    "authors",
+    "venue",
+    "citations",
+    "openAccess",
+    "openAccessUrl",
+    "referencedCount",
+    "doi",
+    "abstract",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const ref = requireOpenAlexWorkRef(kwargs.id);
+    const work = (await fetchOpenAlex(
+      `${OPENALEX_BASE}/works/${encodeURIComponent(ref)}?select=${WORK_SELECT}`,
+      "openalex work",
+    )) as OpenAlexWork;
+    return [mapOpenAlexWorkRow(work)];
+  },
+});