@zenalexa/unicli 0.225.1 → 0.225.3

package/src/adapters/acl-anthology/papers.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveCommand } from "../../registry.js";
+import {
+  aclAnthologyPdfUrl,
+  aclArtifactFilename,
+  cleanAclHtml,
+  normalizeAclAnthologyId,
+  parseAclBibEntries,
+  requireAclReadPageArgs,
+  searchAclBibRows,
+} from "./papers.js";
+
+describe("acl-anthology scholarly commands", () => {
+  it("normalizes source ids and URLs without accepting traversal", () => {
+    expect(normalizeAclAnthologyId("2020.acl-main.447")).toBe(
+      "2020.acl-main.447",
+    );
+    expect(
+      normalizeAclAnthologyId("https://aclanthology.org/2020.acl-main.447.pdf"),
+    ).toBe("2020.acl-main.447");
+    expect(
+      normalizeAclAnthologyId("https://aclanthology.org/2020.acl-main.447/"),
+    ).toBe("2020.acl-main.447");
+    expect(() => normalizeAclAnthologyId("../2020.acl-main.447")).toThrow(
+      "ACL Anthology id",
+    );
+  });
+
+  it("builds official ACL PDF URLs and stable artifact filenames", () => {
+    expect(aclAnthologyPdfUrl("2020.acl-main.447")).toBe(
+      "https://aclanthology.org/2020.acl-main.447.pdf",
+    );
+    expect(
+      aclArtifactFilename({
+        id: "2020.acl-main.447",
+        title: "S2ORC: The Semantic Scholar Open Research Corpus",
+        source_adapter: "acl-anthology",
+        retrieved_at: "2026-06-27T00:00:00Z",
+      }),
+    ).toBe(
+      "2020.acl-main.447-S2ORC__The_Semantic_Scholar_Open_Research_Corpus.pdf",
+    );
+  });
+
+  it("maps scholar read hyphenated arguments to the PDF reader contract", () => {
+    expect(
+      requireAclReadPageArgs({
+        "first-page": "2",
+        "last-page": "4",
+        "max-chars": "1000",
+      }),
+    ).toEqual({ first_page: "2", last_page: "4", max_chars: "1000" });
+  });
+
+  it("registers ACL read as source-level fulltext with pdftotext governance", () => {
+    const command = resolveCommand("acl-anthology", "read")?.command;
+    expect(command?.capabilities).toEqual([
+      "http.fetch",
+      "http.download",
+      "subprocess.exec",
+      "scholar.fulltext",
+      "scholar.pdf",
+    ]);
+    expect(command?.executables).toEqual(["pdftotext"]);
+    expect(command?.minimum_capability).toBe("subprocess.exec");
+  });
+
+  it("parses official ACL BibTeX export rows for source-backed search", () => {
+    const rows = parseAclBibEntries(`
+@inproceedings{lo-etal-2020-s2orc,
+    title = "{S}2{ORC}: The Semantic Scholar Open Research Corpus",
+    author = "Lo, Kyle  and
+      Wang, Lucy Lu  and
+      Neumann, Mark",
+    booktitle = "Proceedings of the 58th Annual Meeting of the Association for Computational Linguistics",
+    year = "2020",
+    url = "https://aclanthology.org/2020.acl-main.447/",
+    doi = "10.18653/v1/2020.acl-main.447",
+    pages = "4969--4983"
+}
+@inproceedings{sharma-etal-2026-council,
+    title = "Council of {LLM}s",
+    author = "Sharma, Vivek",
+    year = "2026",
+    url = "https://aclanthology.org/2026.wassa-1.1/"
+}
+`);
+
+    expect(rows[0]).toMatchObject({
+      id: "2020.acl-main.447",
+      title: "S2ORC: The Semantic Scholar Open Research Corpus",
+      authors: ["Kyle Lo", "Lucy Lu Wang", "Mark Neumann"],
+      year: 2020,
+      doi: "10.18653/v1/2020.acl-main.447",
+      pdf_url: "https://aclanthology.org/2020.acl-main.447.pdf",
+      source_url: "https://aclanthology.org/2020.acl-main.447/",
+    });
+    expect(searchAclBibRows(rows, "Semantic Scholar Corpus", 1)).toEqual([
+      rows[0],
+    ]);
+  });
+
+  it("cleans ACL Anthology title HTML", () => {
+    expect(
+      cleanAclHtml(
+        '<a href="https://aclanthology.org/demo.pdf"><span class="acl-fixed-case">S</span>2ORC</a>',
+      ),
+    ).toBe("S2ORC");
+  });
+});

package/src/adapters/acl-anthology/papers.ts

@@ -1,22 +1,31 @@
 /**
  * @owner       src::adapters::acl-anthology::papers
- * @does        Registers ACL Anthology paper search and event proceedings listing from official Anthology pages.
- * @needs       aclanthology.org static search/event HTML, src/registry.ts
- * @feeds       src/commands/scholar.ts via scholar.search, scholar.get, scholar.pdf, and scholar.venue
- * @breaks      ACL Anthology markup drift surfaces as empty parse output; no browser workaround is used.
- * @invariants  Paper URLs/PDF URLs are absolutized against aclanthology.org; event keys are explicit.
- * @side-effects HTTPS egress to aclanthology.org only
- * @perf        O(N) over one HTML response
+ * @does        Registers ACL Anthology paper search, metadata lookup, PDF download, and PDF text-read commands from official Anthology pages.
+ * @needs       aclanthology.org static search/paper HTML, scholar-artifacts PDF reader, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.search, scholar.get, scholar.pdf, scholar.fulltext, and scholar.venue
+ * @breaks      ACL Anthology markup drift, denied PDF downloads, missing pdftotext, or empty PDF text surfaces as source read failure.
+ * @invariants  Paper URLs/PDF URLs are absolutized against aclanthology.org; read output labels `text_source=pdf`.
+ * @side-effects HTTPS egress to aclanthology.org; read writes PDFs under the requested output directory and executes pdftotext.
+ * @perf        O(N) over one HTML response for search; O(PDF bytes + extracted pages) for read.
  * @concurrency safe
- * @test        covered by scholar command discovery and parser style tests for sibling proceedings sources
+ * @test        src/adapters/acl-anthology/papers.test.ts, tests/unit/adapters/scholar-sources.test.ts
  * @stability   experimental
  * @since       2026-05-19
  */
 
+import { execFile } from "node:child_process";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { gunzipSync } from "node:zlib";
+
 import { cli, Strategy } from "../../registry.js";
+import { httpDownload, sanitizeFilename } from "../../engine/download.js";
 import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
 
 const ORIGIN = "https://aclanthology.org";
+const ANTHOLOGY_BIB_URL = `${ORIGIN}/anthology.bib.gz`;
+const execFileAsync = promisify(execFile);
+let anthologyBibCache: Promise<string> | undefined;
 
 function decode(value: string): string {
   return value
@@ -29,54 +38,206 @@ function decode(value: string): string {
     .trim();
 }
 
-function absolute(path: string): string {
-  return /^https?:\/\//i.test(path)
-    ? path
-    : `${ORIGIN}${path.startsWith("/") ? "" : "/"}${path}`;
+export function cleanAclHtml(value: string): string {
+  return decode(value.replace(/<[^>]+>/g, ""));
+}
+
+function normalizeSearchText(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
 }
 
-function normalizeId(value: unknown): string {
-  const raw = String(value ?? "").trim();
+export function normalizeAclAnthologyId(value: unknown): string {
+  const raw = String(value ?? "")
+    .trim()
+    .replace(/^https?:\/\/(?:www\.)?aclanthology\.org\//i, "")
+    .replace(/\.pdf$/i, "")
+    .replace(/\/$/i, "");
   if (!/^[A-Za-z0-9.-]+$/.test(raw)) {
-    throw new Error(`ACL Anthology id "${raw}" is not valid.`);
+    throw new Error(`ACL Anthology id "${String(value ?? "")}" is not valid.`);
   }
   return raw.replace(/\.$/, "");
 }
 
-function parseRows(
-  html: string,
-  source = "acl-anthology",
-): ScholarlyWorkRecord[] {
-  const out: ScholarlyWorkRecord[] = [];
+export function aclAnthologyPdfUrl(id: string): string {
+  return `${ORIGIN}/${id}.pdf`;
+}
+
+function cleanBibValue(value: string): string {
+  return decode(
+    value
+      .trim()
+      .replace(/,$/, "")
+      .replace(/^["{]|["}]$/g, "")
+      .replace(/\\"/g, '"')
+      .replace(/\\&/g, "&")
+      .replace(/\\url\{([^}]+)\}/g, "$1")
+      .replace(/\\[a-zA-Z]+\{([^}]*)\}/g, "$1")
+      .replace(/[{}]/g, "")
+      .replace(/\s+/g, " "),
+  );
+}
+
+function normalizeBibAuthors(value: string): string[] | undefined {
+  const authors = cleanBibValue(value)
+    .split(/\s+and\s+/)
+    .map((author) => {
+      const parts = author.split(/\s*,\s*/);
+      return parts.length === 2 ? `${parts[1]} ${parts[0]}` : author;
+    })
+    .map((author) => author.trim())
+    .filter(Boolean);
+  return authors.length > 0 ? authors.slice(0, 20) : undefined;
+}
+
+function parseBibFields(entry: string): Record<string, string> {
+  const fields: Record<string, string> = {};
   const re =
-    /<p class="d-sm-flex[^"]*">[\s\S]*?<a[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>([\s\S]*?)(?=<p class="d-sm-flex|$)/g;
+    /^\s*([A-Za-z][A-Za-z0-9_-]*)\s*=\s*([\s\S]*?)(?=,\n\s*[A-Za-z][A-Za-z0-9_-]*\s*=|\n}\s*$)/gm;
   let match: RegExpExecArray | null;
-  while ((match = re.exec(html)) !== null) {
-    const sourceUrl = absolute(match[1]);
-    const id = sourceUrl.replace(`${ORIGIN}/`, "").replace(/\/$/, "");
-    const block = match[3];
-    const pdf = block.match(/href="([^"]+\.pdf)"/i)?.[1] ?? "";
-    const authorText = block
-      .replace(/<span class="d-block">[\s\S]*?<\/span>/g, " ")
-      .replace(/<[^>]+>/g, " ");
-    const authors = decode(authorText)
-      .split(/,\s*/)
-      .map((author) => author.trim())
-      .filter(Boolean)
-      .slice(0, 20);
-    out.push({
+  while ((match = re.exec(entry)) !== null) {
+    fields[match[1].toLowerCase()] = match[2];
+  }
+  return fields;
+}
+
+export function parseAclBibEntries(bib: string): ScholarlyWorkRecord[] {
+  const rows: ScholarlyWorkRecord[] = [];
+  for (const entry of bib.split(/\n(?=@[A-Za-z]+\{)/)) {
+    const header = entry.match(/^@([A-Za-z]+)\{([^,]+),/);
+    if (!header) continue;
+    const fields = parseBibFields(entry);
+    const title = fields.title ? cleanBibValue(fields.title) : "";
+    const sourceUrl = fields.url ? cleanBibValue(fields.url) : "";
+    const id = sourceUrl
+      ? normalizeAclAnthologyId(sourceUrl)
+      : normalizeAclAnthologyId(header[2]);
+    if (!title || !id) continue;
+    const year = fields.year ? Number(cleanBibValue(fields.year)) : undefined;
+    const doi = fields.doi ? cleanBibValue(fields.doi) : undefined;
+    rows.push({
       id,
-      title: decode(match[2].replace(/<[^>]+>/g, " ")),
-      authors: authors.length > 0 ? authors : undefined,
-      year: Number(id.slice(0, 4)) || undefined,
-      venue: "ACL Anthology",
-      pdf_url: pdf ? absolute(pdf) : `${sourceUrl}.pdf`,
-      source_adapter: source,
-      source_url: sourceUrl,
+      title,
+      authors: fields.author ? normalizeBibAuthors(fields.author) : undefined,
+      year: Number.isInteger(year) ? year : undefined,
+      venue: fields.booktitle
+        ? cleanBibValue(fields.booktitle)
+        : "ACL Anthology",
+      doi,
+      pdf_url: aclAnthologyPdfUrl(id),
+      source_adapter: "acl-anthology",
+      source_url: `${ORIGIN}/${id}/`,
       retrieved_at: new Date().toISOString(),
     });
   }
-  return out;
+  return rows;
+}
+
+function scoreAclBibRow(row: ScholarlyWorkRecord, query: string): number {
+  const normalizedQuery = normalizeSearchText(query);
+  const terms = normalizedQuery.split(" ").filter(Boolean);
+  const title = normalizeSearchText(row.title);
+  const authors = normalizeSearchText((row.authors ?? []).join(" "));
+  const haystack = normalizeSearchText(
+    [
+      row.id,
+      row.title,
+      row.venue,
+      row.year,
+      row.doi,
+      (row.authors ?? []).join(" "),
+    ]
+      .filter(Boolean)
+      .join(" "),
+  );
+  if (!normalizedQuery || !terms.every((term) => haystack.includes(term))) {
+    return 0;
+  }
+  let score = 10;
+  if (row.id.toLowerCase() === normalizedQuery) score += 100;
+  if (title === normalizedQuery) score += 80;
+  if (title.includes(normalizedQuery)) score += 40;
+  if (authors.includes(normalizedQuery)) score += 20;
+  return score + Math.min(Number(row.year ?? 0) / 10_000, 1);
+}
+
+export function searchAclBibRows(
+  rows: readonly ScholarlyWorkRecord[],
+  query: string,
+  limit: number,
+): ScholarlyWorkRecord[] {
+  return rows
+    .map((row, index) => ({
+      row,
+      index,
+      score: scoreAclBibRow(row, query),
+    }))
+    .filter((candidate) => candidate.score > 0)
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .slice(0, limit)
+    .map((candidate) => candidate.row);
+}
+
+export function requireAclReadPageArgs(
+  kwargs: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    first_page: kwargs["first-page"] ?? kwargs.firstPage,
+    last_page: kwargs["last-page"] ?? kwargs.lastPage,
+    max_chars: kwargs["max-chars"] ?? kwargs.maxChars,
+  };
+}
+
+export function aclArtifactFilename(record: ScholarlyWorkRecord): string {
+  const title = sanitizeFilename(String(record.title ?? ""))
+    .replace(/\s+/g, "_")
+    .slice(0, 96);
+  return `${sanitizeFilename(record.id)}${title ? `-${title}` : ""}.pdf`;
+}
+
+function requireAclPageRange(
+  firstPage: unknown,
+  lastPage: unknown,
+): { firstPage: number; lastPage: number } {
+  const first = Number(firstPage ?? 1);
+  const last = Number(lastPage ?? 20);
+  if (!Number.isInteger(first) || first < 1) {
+    throw new Error("acl-anthology first-page must be an integer >= 1.");
+  }
+  if (!Number.isInteger(last) || last < first) {
+    throw new Error(
+      "acl-anthology last-page must be an integer >= first-page.",
+    );
+  }
+  return { firstPage: first, lastPage: last };
+}
+
+function requireAclMaxChars(value: unknown, fallback = 40_000): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1_000 || n > 1_000_000) {
+    throw new Error(
+      `acl-anthology max-chars must be an integer in [1000, 1000000]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+function truncateAclText(
+  text: string,
+  maxChars: number,
+): { text: string; truncated: boolean; originalChars: number } {
+  if (text.length <= maxChars) {
+    return { text, truncated: false, originalChars: text.length };
+  }
+  return {
+    text: `${text.slice(0, maxChars).trimEnd()}\n\n[truncated at ${maxChars} characters]`,
+    truncated: true,
+    originalChars: text.length,
+  };
 }
 
 async function fetchHtml(url: string, label: string): Promise<string> {
@@ -93,6 +254,104 @@ async function fetchHtml(url: string, label: string): Promise<string> {
   return response.text();
 }
 
+async function fetchAnthologyBib(): Promise<string> {
+  anthologyBibCache ??= (async () => {
+    const response = await fetch(ANTHOLOGY_BIB_URL, {
+      headers: {
+        Accept: "application/x-gzip, application/gzip, */*",
+        "User-Agent":
+          "unicli-acl-anthology/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      },
+    });
+    if (!response.ok)
+      throw new Error(`ACL Anthology BibTeX returned HTTP ${response.status}.`);
+    return gunzipSync(Buffer.from(await response.arrayBuffer())).toString(
+      "utf8",
+    );
+  })();
+  return anthologyBibCache;
+}
+
+async function fetchAclPaperRecord(id: string): Promise<ScholarlyWorkRecord> {
+  const html = await fetchHtml(`${ORIGIN}/${id}/`, `acl-anthology paper ${id}`);
+  const title = cleanAclHtml(
+    html.match(/<h2[^>]*id=title[^>]*>([\s\S]*?)<\/h2>/)?.[1] ?? "",
+  );
+  if (!title)
+    throw new Error(`ACL Anthology paper ${id} did not expose a title.`);
+  return {
+    id,
+    title,
+    year: Number(id.slice(0, 4)) || undefined,
+    venue: "ACL Anthology",
+    pdf_url: aclAnthologyPdfUrl(id),
+    source_adapter: "acl-anthology",
+    source_url: `${ORIGIN}/${id}/`,
+    retrieved_at: new Date().toISOString(),
+  };
+}
+
+async function readAclPaperPdf(
+  record: ScholarlyWorkRecord,
+  kwargs: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  if (!record.pdf_url) {
+    throw new Error(`ACL Anthology paper ${record.id} did not expose a PDF.`);
+  }
+  const outputDir = resolve(
+    String(kwargs.output ?? "./acl-anthology-downloads"),
+  );
+  const path = join(outputDir, aclArtifactFilename(record));
+  const download = await httpDownload(record.pdf_url, path, {
+    Accept: "application/pdf,*/*",
+    Referer: record.source_url ?? `${ORIGIN}/${record.id}/`,
+    "User-Agent":
+      "unicli-acl-anthology/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+  });
+  if (download.status === "failed" || !download.path) {
+    throw new Error(
+      `ACL Anthology PDF download failed for ${record.id}: ${download.error ?? "no path"}.`,
+    );
+  }
+
+  const pageArgs = requireAclReadPageArgs(kwargs);
+  const { firstPage, lastPage } = requireAclPageRange(
+    pageArgs.first_page,
+    pageArgs.last_page,
+  );
+  const maxChars = requireAclMaxChars(pageArgs.max_chars);
+  const { stdout } = await execFileAsync(
+    "pdftotext",
+    [
+      "-layout",
+      "-enc",
+      "UTF-8",
+      "-f",
+      String(firstPage),
+      "-l",
+      String(lastPage),
+      download.path,
+      "-",
+    ],
+    { timeout: 60_000, maxBuffer: 10 * 1024 * 1024 },
+  );
+  const extracted = stdout.trim();
+  if (!extracted) {
+    throw new Error(
+      `pdftotext returned no text for ACL Anthology ${record.id} pages ${firstPage}-${lastPage}.`,
+    );
+  }
+  const truncated = truncateAclText(extracted, maxChars);
+  return {
+    ...record,
+    path: download.path,
+    text: truncated.text,
+    text_chars: truncated.originalChars,
+    text_truncated: truncated.truncated,
+    text_source: "pdf",
+  };
+}
+
 cli({
   site: "acl-anthology",
   name: "search",
@@ -109,12 +368,11 @@ cli({
     const query = String(kwargs.query ?? "").trim();
     if (!query) throw new Error("acl-anthology search query cannot be empty.");
     const limit = Math.min(Math.max(Number(kwargs.limit ?? 20), 1), 100);
-    const rows = parseRows(
-      await fetchHtml(
-        `${ORIGIN}/search/?q=${encodeURIComponent(query)}`,
-        "acl-anthology search",
-      ),
-    ).slice(0, limit);
+    const rows = searchAclBibRows(
+      parseAclBibEntries(await fetchAnthologyBib()),
+      query,
+      limit,
+    );
     if (rows.length === 0)
       throw new Error(`No ACL Anthology papers matched "${query}".`);
     return rows;
@@ -131,27 +389,77 @@ cli({
   columns: ["id", "title", "authors", "year", "venue", "pdf_url", "source_url"],
   capabilities: ["http.fetch", "scholar.get", "scholar.pdf"],
   func: async (_page, kwargs) => {
-    const id = normalizeId(kwargs.id ?? kwargs.ref);
-    const html = await fetchHtml(
-      `${ORIGIN}/${id}/`,
-      `acl-anthology paper ${id}`,
-    );
-    const title = decode(
-      html.match(/<h2[^>]*id=title[^>]*>([\s\S]*?)<\/h2>/)?.[1] ?? "",
-    );
-    if (!title)
-      throw new Error(`ACL Anthology paper ${id} did not expose a title.`);
-    return [
-      {
-        id,
-        title,
-        year: Number(id.slice(0, 4)) || undefined,
-        venue: "ACL Anthology",
-        pdf_url: `${ORIGIN}/${id}.pdf`,
-        source_adapter: "acl-anthology",
-        source_url: `${ORIGIN}/${id}/`,
-        retrieved_at: new Date().toISOString(),
-      } satisfies ScholarlyWorkRecord,
-    ];
+    const id = normalizeAclAnthologyId(kwargs.id ?? kwargs.ref);
+    return [await fetchAclPaperRecord(id)];
+  },
+});
+
+cli({
+  site: "acl-anthology",
+  name: "read",
+  description: "Download an ACL Anthology paper PDF by id and extract text",
+  domain: "aclanthology.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "ACL Anthology paper id (e.g. 2020.acl-main.447)",
+      "x-unicli-kind": "id",
+      "x-unicli-accepts": ["url"],
+    },
+    {
+      name: "output",
+      type: "str",
+      default: "./acl-anthology-downloads",
+      description: "Output directory",
+      "x-unicli-kind": "path",
+    },
+    {
+      name: "first-page",
+      type: "int",
+      default: 1,
+      description: "First PDF page to extract",
+    },
+    {
+      name: "last-page",
+      type: "int",
+      default: 20,
+      description: "Last PDF page to extract",
+    },
+    {
+      name: "max-chars",
+      type: "int",
+      default: 40000,
+      description: "Maximum extracted text characters",
+    },
+  ],
+  columns: [
+    "id",
+    "title",
+    "source_adapter",
+    "source_url",
+    "pdf_url",
+    "path",
+    "text_source",
+    "text",
+    "text_chars",
+    "text_truncated",
+  ],
+  capabilities: [
+    "http.fetch",
+    "http.download",
+    "subprocess.exec",
+    "scholar.fulltext",
+    "scholar.pdf",
+  ],
+  executables: ["pdftotext"],
+  minimum_capability: "subprocess.exec",
+  func: async (_page, kwargs) => {
+    const id = normalizeAclAnthologyId(kwargs.id ?? kwargs.ref);
+    const record = await fetchAclPaperRecord(id);
+    return [await readAclPaperPdf(record, kwargs)];
   },
 });

package/src/adapters/arxiv/papers.test.ts

@@ -1,9 +1,14 @@
 import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
 import {
+  arxivArtifactFilename,
   decodeArxivEntities,
+  normalizeArxivId,
   parseArxivEntries,
   requireArxivAuthor,
   requireArxivCategory,
+  requireArxivMaxChars,
+  requireArxivPageRange,
   requireArxivLimit,
 } from "./papers.js";
 
@@ -19,6 +24,47 @@ describe("arxiv agent-facing author and recent commands", () => {
     expect(() => requireArxivLimit("51", 20)).toThrow("arxiv limit");
   });
 
+  it("validates read IDs, page ranges, max text bounds, and filenames", () => {
+    expect(normalizeArxivId("arxiv:1706.03762v7")).toBe("1706.03762v7");
+    expect(normalizeArxivId("https://arxiv.org/abs/1706.03762")).toBe(
+      "1706.03762",
+    );
+    expect(normalizeArxivId("https://arxiv.org/pdf/hep-th/9901001.pdf")).toBe(
+      "hep-th/9901001",
+    );
+    expect(() => normalizeArxivId("../1706.03762")).toThrow("Invalid arXiv");
+    expect(requireArxivPageRange("2", "4")).toEqual({
+      firstPage: 2,
+      lastPage: 4,
+    });
+    expect(() => requireArxivPageRange("0", "4")).toThrow("first-page");
+    expect(() => requireArxivPageRange("4", "3")).toThrow("last-page");
+    expect(requireArxivMaxChars(undefined)).toBe(40000);
+    expect(() => requireArxivMaxChars("999")).toThrow("max-chars");
+    expect(
+      arxivArtifactFilename({
+        id: "1706.03762v7",
+        title: "Attention / Is: All? You Need",
+      }),
+    ).toBe("1706.03762v7-Attention-Is-All-You-Need.pdf");
+  });
+
+  it("registers arxiv read as a source-level fulltext command", () => {
+    expect(resolveCommand("arxiv", "read")?.command.capabilities).toEqual([
+      "http.fetch",
+      "http.download",
+      "subprocess.exec",
+      "scholar.fulltext",
+      "scholar.pdf",
+    ]);
+    expect(resolveCommand("arxiv", "read")?.command.minimum_capability).toBe(
+      "subprocess.exec",
+    );
+    expect(resolveCommand("arxiv", "read")?.command.executables).toEqual([
+      "pdftotext",
+    ]);
+  });
+
   it("decodes entities and parses Atom entries", () => {
     expect(decodeArxivEntities("A &amp; B &lt; C")).toBe("A & B < C");
     expect(