@zenalexa/unicli 0.221.0 → 0.222.0

package/src/adapters/neurips/proceedings.ts

@@ -0,0 +1,126 @@
+/**
+ * @owner       src::adapters::neurips::proceedings
+ * @does        Registers NeurIPS proceedings search over the official yearly paper list.
+ * @needs       proceedings.neurips.cc static HTML, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.search, scholar.pdf, and scholar.venue
+ * @breaks      NeurIPS markup drift surfaces as empty parse output; no unrelated source fallback is used.
+ * @invariants  Year is explicit; paper URLs are absolutized against proceedings.neurips.cc.
+ * @side-effects HTTPS egress to proceedings.neurips.cc only
+ * @perf        O(N) over one proceedings HTML page
+ * @concurrency safe
+ * @test        tests/unit/adapters/scholar-sources.test.ts
+ * @stability   experimental
+ * @since       2026-05-19
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
+
+const ORIGIN = "https://proceedings.neurips.cc";
+
+function decode(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function absolute(path: string): string {
+  return /^https?:\/\//i.test(path)
+    ? path
+    : `${ORIGIN}${path.startsWith("/") ? "" : "/"}${path}`;
+}
+
+function requireYear(value: unknown): string {
+  const year = String(value ?? "").trim();
+  if (!/^\d{4}$/.test(year))
+    throw new Error(`neurips year "${year}" is not valid.`);
+  return year;
+}
+
+export function parseNeuripsRows(
+  html: string,
+  year = "2024",
+): ScholarlyWorkRecord[] {
+  const out: ScholarlyWorkRecord[] = [];
+  const re =
+    /<div class="paper-content">[\s\S]*?<a title="paper title" href="([^"]+)">([\s\S]*?)<\/a>[\s\S]*?<span class="paper-authors">([\s\S]*?)<\/span>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(html)) !== null) {
+    const sourceUrl = absolute(match[1]);
+    out.push({
+      id:
+        sourceUrl
+          .split("/")
+          .pop()
+          ?.replace(/\.html$/, "") ?? decode(match[2]),
+      title: decode(match[2].replace(/<[^>]+>/g, " ")),
+      authors: decode(match[3])
+        .split(",")
+        .map((author) => author.trim())
+        .filter(Boolean),
+      year: Number(year),
+      venue: "NeurIPS",
+      pdf_url: sourceUrl
+        .replace("-Abstract-", "-Paper-")
+        .replace(/\.html$/, ".pdf"),
+      source_adapter: "neurips",
+      source_url: sourceUrl,
+      retrieved_at: new Date().toISOString(),
+    });
+  }
+  return out;
+}
+
+cli({
+  site: "neurips",
+  name: "search",
+  description: "Search NeurIPS proceedings by year",
+  domain: "proceedings.neurips.cc",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "year", type: "str", default: "2024" },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["id", "title", "authors", "year", "venue", "pdf_url", "source_url"],
+  capabilities: [
+    "http.fetch",
+    "scholar.search",
+    "scholar.venue",
+    "scholar.pdf",
+  ],
+  func: async (_page, kwargs) => {
+    const query = String(kwargs.query ?? "")
+      .trim()
+      .toLowerCase();
+    if (!query) throw new Error("neurips search query cannot be empty.");
+    const year = requireYear(kwargs.year);
+    const response = await fetch(`${ORIGIN}/paper_files/paper/${year}`, {
+      headers: {
+        Accept: "text/html",
+        "User-Agent":
+          "unicli-neurips/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      },
+    });
+    if (response.status === 404)
+      throw new Error(`NeurIPS ${year} returned no proceedings page.`);
+    if (!response.ok)
+      throw new Error(`NeurIPS ${year} returned HTTP ${response.status}.`);
+    const limit = Math.min(Math.max(Number(kwargs.limit ?? 20), 1), 200);
+    const rows = parseNeuripsRows(await response.text(), year)
+      .filter((row) =>
+        `${row.title} ${row.authors?.join(" ") ?? ""}`
+          .toLowerCase()
+          .includes(query),
+      )
+      .slice(0, limit);
+    if (rows.length === 0)
+      throw new Error(`No NeurIPS ${year} papers matched "${query}".`);
+    return rows;
+  },
+});

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

@@ -31,38 +31,46 @@ describe("openalex agent-facing commands", () => {
   });
 
   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",
-      },
-    ]);
+    const rows = 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,
+    );
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      rank: 1,
+      id: "W1234",
+      title: "A paper",
+      year: 2026,
+      citations: 5,
+      firstAuthor: "Ada",
+      authors: ["Ada"],
+      venue: "Journal",
+      openAccess: true,
+      is_open_access: true,
+      type: "article",
+      doi: "10.1/example",
+      pdf_url: "",
+      openalex_id: "W1234",
+      source_adapter: "openalex",
+      source_url: "https://openalex.org/W1234",
+      url: "https://openalex.org/W1234",
+    });
+    expect(rows[0]?.retrieved_at).toEqual(
+      expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+    );
   });
 
   it("maps work detail rows", () => {

package/src/adapters/openalex/works.ts

@@ -164,6 +164,14 @@ function authors(work: OpenAlexWork): string {
     : "";
 }
 
+function authorList(work: OpenAlexWork): string[] {
+  return Array.isArray(work.authorships)
+    ? work.authorships
+        .map((item) => stringField(item.author?.display_name).trim())
+        .filter(Boolean)
+    : [];
+}
+
 function venue(work: OpenAlexWork): string {
   return stringField(work.primary_location?.source?.display_name).trim();
 }
@@ -181,10 +189,17 @@ export function mapOpenAlexSearchRows(
       year: numberField(work.publication_year),
       citations: numberField(work.cited_by_count),
       firstAuthor: firstAuthor(work),
+      authors: authorList(work),
       venue: venue(work),
       openAccess: Boolean(work.open_access?.is_oa),
+      is_open_access: Boolean(work.open_access?.is_oa),
       type: stringField(work.type).trim(),
       doi: bareDoi(work.doi),
+      pdf_url: stringField(work.open_access?.oa_url).trim(),
+      openalex_id: id,
+      source_adapter: "openalex",
+      source_url: id ? `https://openalex.org/${id}` : "",
+      retrieved_at: new Date().toISOString(),
       url: id ? `https://openalex.org/${id}` : "",
     };
   });
@@ -203,15 +218,26 @@ export function mapOpenAlexWorkRow(
     date: stringField(work.publication_date).trim(),
     language: stringField(work.language).trim(),
     authors: authors(work),
+    author_list: authorList(work),
     venue: venue(work),
     citations: numberField(work.cited_by_count),
+    cited_by_count: numberField(work.cited_by_count),
     openAccess: Boolean(work.open_access?.is_oa),
+    is_open_access: Boolean(work.open_access?.is_oa),
     openAccessUrl: stringField(work.open_access?.oa_url).trim(),
+    pdf_url: stringField(work.open_access?.oa_url).trim(),
     referencedCount: Array.isArray(work.referenced_works)
       ? work.referenced_works.length
       : null,
+    references_count: Array.isArray(work.referenced_works)
+      ? work.referenced_works.length
+      : null,
     doi: bareDoi(work.doi),
     abstract: reconstructOpenAlexAbstract(work.abstract_inverted_index),
+    openalex_id: id,
+    source_adapter: "openalex",
+    source_url: `https://openalex.org/${id}`,
+    retrieved_at: new Date().toISOString(),
     url: `https://openalex.org/${id}`,
   };
 }
@@ -259,6 +285,7 @@ cli({
     "doi",
     "url",
   ],
+  capabilities: ["http.fetch", "scholar.search"],
   func: async (_page, kwargs) => {
     const query = requireOpenAlexString(kwargs.query, "query");
     const limit = requireOpenAlexLimit(kwargs.limit);
@@ -308,6 +335,12 @@ cli({
     "abstract",
     "url",
   ],
+  capabilities: [
+    "http.fetch",
+    "scholar.get",
+    "scholar.pdf",
+    "scholar.references",
+  ],
   func: async (_page, kwargs) => {
     const ref = requireOpenAlexWorkRef(kwargs.id);
     const work = (await fetchOpenAlex(

package/src/adapters/openreview/papers.ts

@@ -303,6 +303,7 @@ cli({
     { name: "limit", type: "int", default: 25, description: "Max results" },
   ],
   columns: ["rank", "id", "title", "authors", "venue", "pdate", "url"],
+  capabilities: ["http.fetch", "scholar.search", "scholar.review"],
   func: async (_page, kwargs) => {
     const query = String(kwargs.query ?? "").trim();
     if (!query) throw new Error("openreview search query cannot be empty.");
@@ -363,6 +364,7 @@ cli({
     "pdf",
     "url",
   ],
+  capabilities: ["http.fetch", "scholar.get", "scholar.pdf", "scholar.review"],
   func: async (_page, kwargs) => {
     const id = requireForumId(kwargs.id);
     const notes = notesFromEnvelope(
@@ -409,6 +411,7 @@ cli({
     { name: "limit", type: "int", default: 50, description: "Max submissions" },
   ],
   columns: ["rank", "id", "title", "authors", "venue", "pdate", "url"],
+  capabilities: ["http.fetch", "scholar.author", "scholar.search"],
   func: async (_page, kwargs) => {
     const profile = requireProfileId(kwargs.profile);
     const limit = requireOpenReviewLimit(kwargs.limit, 50, 1000);
@@ -473,6 +476,7 @@ cli({
     "pdf",
     "url",
   ],
+  capabilities: ["http.fetch", "scholar.venue", "scholar.search"],
   func: async (_page, kwargs) => {
     const venue = String(kwargs.venue ?? "").trim();
     if (!venue) throw new Error("openreview venue cannot be empty.");
@@ -531,6 +535,7 @@ cli({
     },
   ],
   columns: ["type", "author", "rating", "confidence", "text"],
+  capabilities: ["http.fetch", "scholar.review"],
   func: async (_page, kwargs) => {
     const forum = requireForumId(kwargs.forum, "forum");
     const maxLength = coerceOpenReviewInt(

package/src/adapters/pmlr/proceedings.ts

@@ -0,0 +1,167 @@
+/**
+ * @owner       src::adapters::pmlr::proceedings
+ * @does        Registers Proceedings of Machine Learning Research volume search using official citeproc.yaml metadata.
+ * @needs       proceedings.mlr.press citeproc.yaml files, js-yaml, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.search, scholar.get, scholar.pdf, and scholar.venue
+ * @breaks      Missing volume metadata or citeproc drift surfaces as explicit adapter errors.
+ * @invariants  Volume is explicit; rows are filtered locally from official YAML metadata, not scraped from rendered cards.
+ * @side-effects HTTPS egress to proceedings.mlr.press only
+ * @perf        O(N) over one proceedings volume
+ * @concurrency safe
+ * @test        tests/unit/adapters/scholar-sources.test.ts
+ * @stability   experimental
+ * @since       2026-05-19
+ */
+
+import yaml from "js-yaml";
+import { cli, Strategy } from "../../registry.js";
+import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
+
+interface PmlrEntry {
+  title?: unknown;
+  abstract?: unknown;
+  URL?: unknown;
+  PDF?: unknown;
+  "container-title"?: unknown;
+  author?: Array<{ given?: unknown; family?: unknown }>;
+  id?: unknown;
+  issued?: { "date-parts"?: unknown[] };
+  volume?: unknown;
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function authors(value: PmlrEntry["author"]): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value
+    .map((person) =>
+      [person.given, person.family].map(str).filter(Boolean).join(" "),
+    )
+    .filter(Boolean);
+  return out.length > 0 ? out : undefined;
+}
+
+function issuedYear(entry: PmlrEntry): number | undefined {
+  const first = entry.issued?.["date-parts"]?.[0];
+  return typeof first === "number" && Number.isFinite(first)
+    ? first
+    : undefined;
+}
+
+export function parsePmlrCiteproc(text: string): PmlrEntry[] {
+  const parsed = yaml.load(text);
+  return Array.isArray(parsed) ? (parsed as PmlrEntry[]) : [];
+}
+
+export function mapPmlrEntry(
+  entry: PmlrEntry,
+  source: string,
+): ScholarlyWorkRecord {
+  const id = str(entry.id);
+  if (!id) throw new Error("PMLR entry did not include id.");
+  return {
+    id,
+    title: str(entry.title),
+    abstract: str(entry.abstract) || undefined,
+    authors: authors(entry.author),
+    year: issuedYear(entry),
+    venue: str(entry["container-title"]) || undefined,
+    type: entry.volume ? `pmlr:${String(entry.volume)}` : "pmlr",
+    pdf_url: str(entry.PDF) || undefined,
+    source_adapter: source,
+    source_url: str(entry.URL) || undefined,
+    retrieved_at: new Date().toISOString(),
+  };
+}
+
+function requireVolume(value: unknown): string {
+  const raw = String(value ?? "")
+    .trim()
+    .replace(/^v/i, "");
+  if (!/^\d+$/.test(raw))
+    throw new Error(`pmlr volume "${String(value)}" is not valid.`);
+  return raw;
+}
+
+async function fetchVolume(volume: string): Promise<PmlrEntry[]> {
+  const response = await fetch(
+    `https://proceedings.mlr.press/v${volume}/assets/bib/citeproc.yaml`,
+    {
+      headers: {
+        Accept: "application/x-yaml,text/yaml,text/plain",
+        "User-Agent": "unicli-pmlr/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      },
+    },
+  );
+  if (response.status === 404)
+    throw new Error(`PMLR volume v${volume} returned no metadata.`);
+  if (!response.ok)
+    throw new Error(`PMLR volume v${volume} returned HTTP ${response.status}.`);
+  return parsePmlrCiteproc(await response.text());
+}
+
+cli({
+  site: "pmlr",
+  name: "search",
+  description: "Search a PMLR proceedings volume (e.g. v235 for ICML 2024)",
+  domain: "proceedings.mlr.press",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "volume", type: "str", default: "235" },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["id", "title", "authors", "year", "venue", "pdf_url", "source_url"],
+  capabilities: [
+    "http.fetch",
+    "scholar.search",
+    "scholar.venue",
+    "scholar.pdf",
+  ],
+  func: async (_page, kwargs) => {
+    const query = String(kwargs.query ?? "")
+      .trim()
+      .toLowerCase();
+    if (!query) throw new Error("pmlr search query cannot be empty.");
+    const volume = requireVolume(kwargs.volume);
+    const limit = Math.min(Math.max(Number(kwargs.limit ?? 20), 1), 200);
+    const rows = (await fetchVolume(volume))
+      .map((entry) => mapPmlrEntry(entry, "pmlr"))
+      .filter((row) =>
+        `${row.title} ${row.abstract ?? ""} ${row.authors?.join(" ") ?? ""}`
+          .toLowerCase()
+          .includes(query),
+      )
+      .slice(0, limit);
+    if (rows.length === 0)
+      throw new Error(`No PMLR v${volume} papers matched "${query}".`);
+    return rows;
+  },
+});
+
+cli({
+  site: "pmlr",
+  name: "paper",
+  description: "Fetch a PMLR paper by id inside a proceedings volume",
+  domain: "proceedings.mlr.press",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "id", type: "str", required: true, positional: true },
+    { name: "volume", type: "str", default: "235" },
+  ],
+  columns: ["id", "title", "authors", "year", "venue", "pdf_url", "source_url"],
+  capabilities: ["http.fetch", "scholar.get", "scholar.pdf"],
+  func: async (_page, kwargs) => {
+    const id = String(kwargs.id ?? kwargs.ref ?? "").trim();
+    if (!id) throw new Error("pmlr paper id is required.");
+    const volume = requireVolume(kwargs.volume);
+    const row = (await fetchVolume(volume))
+      .map((entry) => mapPmlrEntry(entry, "pmlr"))
+      .find((entry) => entry.id === id);
+    if (!row)
+      throw new Error(`No PMLR v${volume} paper found with id "${id}".`);
+    return [row];
+  },
+});

package/src/adapters/pubmed/articles.ts

@@ -304,6 +304,7 @@ cli({
     { name: "limit", type: "int", default: 20, description: "Max results" },
   ],
   columns: SUMMARY_COLUMNS,
+  capabilities: ["http.fetch", "scholar.search"],
   func: async (_page, kwargs) => {
     const query = requirePubMedText(kwargs.query, "query");
     const limit = requirePubMedLimit(kwargs.limit);
@@ -345,6 +346,7 @@ cli({
     },
   ],
   columns: ["field", "value"],
+  capabilities: ["http.fetch", "scholar.get"],
   func: async (_page, kwargs) => {
     const pmid = requirePmid(kwargs.pmid);
     const xml = String(
@@ -371,6 +373,7 @@ cli({
     { name: "limit", type: "int", default: 20, description: "Max results" },
   ],
   columns: SUMMARY_COLUMNS,
+  capabilities: ["http.fetch", "scholar.author", "scholar.search"],
   func: async (_page, kwargs) => {
     const name = requirePubMedText(kwargs.name, "author");
     const limit = requirePubMedLimit(kwargs.limit);
@@ -414,6 +417,7 @@ cli({
     { name: "limit", type: "int", default: 20, description: "Max results" },
   ],
   columns: SUMMARY_COLUMNS,
+  capabilities: ["http.fetch", "scholar.citations", "scholar.references"],
   func: async (_page, kwargs) => {
     const pmid = requirePmid(kwargs.pmid);
     const direction = requireChoice(
@@ -459,6 +463,7 @@ cli({
     { name: "limit", type: "int", default: 20, description: "Max results" },
   ],
   columns: RELATED_COLUMNS,
+  capabilities: ["http.fetch", "scholar.search"],
   func: async (_page, kwargs) => {
     const pmid = requirePmid(kwargs.pmid);
     const limit = requirePubMedLimit(kwargs.limit);