@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/nuget/package.ts

@@ -0,0 +1,193 @@
+/**
+ * @owner   src/adapters/nuget/package.ts
+ * @does    Register agent-facing NuGet package version-history command.
+ * @needs   api.nuget.org registration index and leaf-page pagination.
+ * @feeds   surface coverage ledger, .NET dependency inspection, registry command surface.
+ * @breaks  NuGet registration stubs or malformed catalog entries hide package release history.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const NUGET_REGISTRATION_BASE =
+  "https://api.nuget.org/v3/registration5-semver1";
+
+interface NugetCatalogEntry {
+  id?: unknown;
+  version?: unknown;
+  title?: unknown;
+  authors?: unknown;
+  tags?: unknown;
+  language?: unknown;
+  licenseExpression?: unknown;
+  projectUrl?: unknown;
+  published?: unknown;
+  listed?: unknown;
+}
+
+interface NugetRegistrationItem {
+  catalogEntry?: NugetCatalogEntry;
+}
+
+interface NugetRegistrationPage {
+  "@id"?: unknown;
+  items?: NugetRegistrationItem[];
+}
+
+interface NugetRegistrationBody {
+  items?: NugetRegistrationPage[];
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function requireNugetPackageId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+    throw new Error("nuget package id must be a non-empty package token.");
+  }
+  return id;
+}
+
+function joinAuthors(value: unknown): string {
+  return Array.isArray(value)
+    ? value.map(stringField).filter(Boolean).join(", ")
+    : stringField(value);
+}
+
+function joinTags(value: unknown): string {
+  return Array.isArray(value)
+    ? value.map(stringField).filter(Boolean).join(", ")
+    : stringField(value);
+}
+
+export async function collectNugetEntries(
+  body: NugetRegistrationBody,
+  fetchLeaf: (url: string) => Promise<NugetRegistrationPage>,
+): Promise<NugetRegistrationItem[]> {
+  const pages = Array.isArray(body.items) ? body.items : [];
+  const entries: NugetRegistrationItem[] = [];
+  for (const [index, page] of pages.entries()) {
+    let pageItems = Array.isArray(page.items) ? page.items : null;
+    if (!pageItems) {
+      const url = stringField(page["@id"]);
+      if (!url) {
+        throw new Error(
+          `nuget package registration page ${index + 1} is missing @id.`,
+        );
+      }
+      const leaf = await fetchLeaf(url);
+      if (!Array.isArray(leaf.items)) {
+        throw new Error(`nuget package registration leaf has no items array.`);
+      }
+      pageItems = leaf.items;
+    }
+    for (const item of pageItems) {
+      if (!item?.catalogEntry || typeof item.catalogEntry !== "object") {
+        throw new Error(
+          `nuget package registration page ${index + 1} has a malformed version entry.`,
+        );
+      }
+      entries.push(item);
+    }
+  }
+  return entries;
+}
+
+export function mapNugetPackageRows(
+  entries: NugetRegistrationItem[],
+  requested: string,
+): Array<Record<string, unknown>> {
+  if (entries.length === 0) {
+    throw new Error(
+      `No published versions found for NuGet package "${requested}".`,
+    );
+  }
+  const sorted = [...entries].sort((a, b) => {
+    const ap = stringField(a.catalogEntry?.published);
+    const bp = stringField(b.catalogEntry?.published);
+    if (ap !== bp) return bp.localeCompare(ap);
+    return stringField(b.catalogEntry?.version).localeCompare(
+      stringField(a.catalogEntry?.version),
+    );
+  });
+  return sorted.map((entry, index) => {
+    const cat = entry.catalogEntry ?? {};
+    const id = stringField(cat.id) || requested;
+    const version = stringField(cat.version);
+    return {
+      rank: index + 1,
+      id,
+      version,
+      title: stringField(cat.title),
+      authors: joinAuthors(cat.authors),
+      tags: joinTags(cat.tags),
+      language: stringField(cat.language),
+      licenseExpression: stringField(cat.licenseExpression),
+      projectUrl: stringField(cat.projectUrl),
+      published: stringField(cat.published),
+      listed: typeof cat.listed === "boolean" ? cat.listed : null,
+      url: version ? `https://www.nuget.org/packages/${id}/${version}` : "",
+    };
+  });
+}
+
+async function fetchNugetJson(url: string, label: string): Promise<unknown> {
+  const response = await fetch(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.ok)
+    throw new Error(`${label} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "nuget",
+  name: "package",
+  description: "Full NuGet package version history",
+  domain: "api.nuget.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "NuGet package id",
+    },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "version",
+    "title",
+    "authors",
+    "tags",
+    "language",
+    "licenseExpression",
+    "projectUrl",
+    "published",
+    "listed",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireNugetPackageId(kwargs.id);
+    const body = (await fetchNugetJson(
+      `${NUGET_REGISTRATION_BASE}/${encodeURIComponent(id.toLowerCase())}/index.json`,
+      `nuget package ${id}`,
+    )) as NugetRegistrationBody;
+    const entries = await collectNugetEntries(
+      body,
+      async (url) =>
+        (await fetchNugetJson(
+          url,
+          "nuget package page",
+        )) as NugetRegistrationPage,
+    );
+    return mapNugetPackageRows(entries, id);
+  },
+});

package/src/adapters/nvd/cve.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { mapNvdCveRow, requireCveId } from "./cve.js";
+
+describe("nvd agent-facing CVE command", () => {
+  it("validates CVE identifiers", () => {
+    expect(requireCveId("cve-2021-44228")).toBe("CVE-2021-44228");
+    expect(() => requireCveId("")).toThrow("nvd CVE id is required");
+    expect(() => requireCveId("GHSA-xxxx-yyyy-zzzz")).toThrow(
+      "not a valid CVE identifier",
+    );
+  });
+
+  it("maps NVD CVE rows with primary CVSS and CWE fields", () => {
+    expect(
+      mapNvdCveRow(
+        {
+          id: "CVE-2021-44228",
+          published: "2021-12-10T10:15:00.000",
+          lastModified: "2026-01-01T00:00:00.000",
+          vulnStatus: "Analyzed",
+          descriptions: [
+            { lang: "es", value: "Spanish" },
+            { lang: "en", value: "Log4Shell" },
+          ],
+          metrics: {
+            cvssMetricV31: [
+              {
+                type: "Primary",
+                cvssData: {
+                  baseScore: 10,
+                  baseSeverity: "CRITICAL",
+                  attackVector: "NETWORK",
+                },
+              },
+            ],
+          },
+          weaknesses: [
+            {
+              description: [{ value: "CWE-20" }, { value: "CWE-20" }],
+            },
+            {
+              description: [{ value: "CWE-502" }],
+            },
+          ],
+          cisaExploitAdd: "2021-12-10",
+        },
+        "CVE-2021-44228",
+      ),
+    ).toEqual({
+      id: "CVE-2021-44228",
+      published: "2021-12-10",
+      lastModified: "2026-01-01",
+      vulnStatus: "Analyzed",
+      baseScore: 10,
+      severity: "CRITICAL",
+      attackVector: "NETWORK",
+      cwe: "CWE-20, CWE-502",
+      kevAdded: "2021-12-10",
+      description: "Log4Shell",
+      url: "https://nvd.nist.gov/vuln/detail/CVE-2021-44228",
+    });
+    expect(() => mapNvdCveRow({}, "CVE-2099-0001")).toThrow(
+      'NVD has no record for "CVE-2099-0001"',
+    );
+  });
+});

package/src/adapters/nvd/cve.ts

@@ -0,0 +1,182 @@
+/**
+ * @owner   src/adapters/nvd/cve.ts
+ * @does    Register agent-facing NVD CVE lookup command.
+ * @needs   Public NVD CVE API 2.0, TypeScript adapter loader, CVE id validation.
+ * @feeds   surface coverage ledger, vulnerability intelligence command surface, agent-readable CVE rows.
+ * @breaks  NVD API envelope drift, weak CVE parsing, or silent empty rows hide vulnerability lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const NVD_BASE = "https://services.nvd.nist.gov/rest/json/cves/2.0";
+const CVE_ID_RE = /^CVE-\d{4}-\d{4,}$/i;
+
+interface NvdDescription {
+  lang?: unknown;
+  value?: unknown;
+}
+
+interface NvdMetric {
+  type?: unknown;
+  baseSeverity?: unknown;
+  cvssData?: {
+    baseScore?: unknown;
+    baseSeverity?: unknown;
+    attackVector?: unknown;
+  };
+}
+
+interface NvdCve {
+  id?: unknown;
+  published?: unknown;
+  lastModified?: unknown;
+  vulnStatus?: unknown;
+  descriptions?: NvdDescription[];
+  metrics?: {
+    cvssMetricV31?: NvdMetric[];
+    cvssMetricV30?: NvdMetric[];
+    cvssMetricV2?: NvdMetric[];
+  };
+  weaknesses?: Array<{
+    description?: Array<{
+      value?: unknown;
+    }>;
+  }>;
+  cisaExploitAdd?: unknown;
+}
+
+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 requireCveId(value: unknown): string {
+  const id = String(value ?? "")
+    .trim()
+    .toUpperCase();
+  if (!id) throw new Error("nvd CVE id is required.");
+  if (!CVE_ID_RE.test(id)) {
+    throw new Error(
+      `nvd CVE id "${String(value)}" is not a valid CVE identifier.`,
+    );
+  }
+  return id;
+}
+
+function pickEnglishDescription(
+  descriptions: NvdDescription[] | undefined,
+): string {
+  if (!Array.isArray(descriptions)) return "";
+  const english = descriptions.find((description) => description.lang === "en");
+  return stringField(english?.value ?? descriptions[0]?.value).trim();
+}
+
+function pickPrimaryCvss(metrics: NvdCve["metrics"]): NvdMetric | null {
+  if (!metrics || typeof metrics !== "object") return null;
+  const candidates = [
+    ...(Array.isArray(metrics.cvssMetricV31) ? metrics.cvssMetricV31 : []),
+    ...(Array.isArray(metrics.cvssMetricV30) ? metrics.cvssMetricV30 : []),
+    ...(Array.isArray(metrics.cvssMetricV2) ? metrics.cvssMetricV2 : []),
+  ];
+  return (
+    candidates.find((metric) => metric.type === "Primary") ??
+    candidates[0] ??
+    null
+  );
+}
+
+function joinCwes(weaknesses: NvdCve["weaknesses"]): string {
+  if (!Array.isArray(weaknesses)) return "";
+  const ids = new Set<string>();
+  for (const weakness of weaknesses) {
+    for (const description of weakness.description ?? []) {
+      const value = stringField(description.value);
+      if (value) ids.add(value);
+    }
+  }
+  return [...ids].join(", ");
+}
+
+export function mapNvdCveRow(
+  cve: NvdCve,
+  requestedId: string,
+): Record<string, unknown> {
+  if (!cve.id) throw new Error(`NVD has no record for "${requestedId}".`);
+  const cvss = pickPrimaryCvss(cve.metrics);
+  const cvssData = cvss?.cvssData ?? {};
+  return {
+    id: stringField(cve.id),
+    published: stringField(cve.published).slice(0, 10),
+    lastModified: stringField(cve.lastModified).slice(0, 10),
+    vulnStatus: stringField(cve.vulnStatus),
+    baseScore: numberField(cvssData.baseScore),
+    severity:
+      stringField(cvssData.baseSeverity) || stringField(cvss?.baseSeverity),
+    attackVector: stringField(cvssData.attackVector),
+    cwe: joinCwes(cve.weaknesses),
+    kevAdded: cve.cisaExploitAdd
+      ? stringField(cve.cisaExploitAdd).slice(0, 10)
+      : "",
+    description: pickEnglishDescription(cve.descriptions),
+    url: `https://nvd.nist.gov/vuln/detail/${String(cve.id)}`,
+  };
+}
+
+async function fetchNvdJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (response.status === 403) throw new Error("nvd cve returned HTTP 403.");
+  if (response.status === 429) throw new Error("nvd cve returned HTTP 429.");
+  if (!response.ok)
+    throw new Error(`nvd cve returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "nvd",
+  name: "cve",
+  description: "NIST NVD CVE detail",
+  domain: "services.nvd.nist.gov",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "CVE identifier",
+    },
+  ],
+  columns: [
+    "id",
+    "published",
+    "lastModified",
+    "vulnStatus",
+    "baseScore",
+    "severity",
+    "attackVector",
+    "cwe",
+    "kevAdded",
+    "description",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireCveId(kwargs.id);
+    const body = (await fetchNvdJson(
+      `${NVD_BASE}?cveId=${encodeURIComponent(id)}`,
+    )) as {
+      vulnerabilities?: Array<{ cve?: NvdCve }>;
+    };
+    const cve = Array.isArray(body.vulnerabilities)
+      ? body.vulnerabilities[0]?.cve
+      : undefined;
+    return [mapNvdCveRow(cve ?? {}, id)];
+  },
+});

package/src/adapters/oeis/sequences.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatOeisId,
+  mapOeisSearchRows,
+  mapOeisSequenceRow,
+  previewOeisTerms,
+  requireOeisLimit,
+  requireOeisSequenceId,
+} from "./sequences.js";
+
+describe("oeis agent-facing sequence commands", () => {
+  it("validates ids and limits", () => {
+    expect(requireOeisLimit(undefined)).toBe(10);
+    expect(requireOeisLimit("100")).toBe(100);
+    expect(() => requireOeisLimit("101")).toThrow("oeis limit must");
+    expect(requireOeisSequenceId("https://oeis.org/A000045")).toBe("A000045");
+    expect(() => requireOeisSequenceId("B45")).toThrow("valid A-number");
+  });
+
+  it("formats ids and term previews", () => {
+    expect(formatOeisId(45)).toBe("A000045");
+    expect(previewOeisTerms("1, 1,2,3", 3)).toBe("1, 1, 2, (+1)");
+  });
+
+  it("maps search rows", () => {
+    expect(
+      mapOeisSearchRows([
+        {
+          number: 45,
+          name: "Fibonacci numbers",
+          keyword: "nonn,easy",
+          data: "0,1,1,2,3,5,8",
+          author: "N. J. A. Sloane",
+          created: "1964-01-01",
+        },
+      ]),
+    ).toMatchObject([
+      {
+        rank: 1,
+        id: "A000045",
+        name: "Fibonacci numbers",
+        preview: "0, 1, 1, 2, 3, 5, 8",
+        url: "https://oeis.org/A000045",
+      },
+    ]);
+  });
+
+  it("maps sequence detail rows", () => {
+    expect(
+      mapOeisSequenceRow(
+        {
+          number: 45,
+          data: "0,1,1",
+          revision: 100,
+          comment: ["a"],
+          formula: ["b"],
+          reference: ["c"],
+          xref: ["d"],
+          link: ["e"],
+        },
+        "A000045",
+      ),
+    ).toMatchObject({
+      id: "A000045",
+      termCount: 3,
+      revision: 100,
+      commentCount: 1,
+      formulaCount: 1,
+    });
+  });
+});