@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/osv/security.ts

@@ -0,0 +1,298 @@
+/**
+ * @owner   src/adapters/osv/security.ts
+ * @does    Register agent-facing OSV.dev package query and vulnerability detail commands.
+ * @needs   Public OSV.dev API, TypeScript adapter loader, bounded argument parsing.
+ * @feeds   surface coverage ledger, vulnerability intelligence command surface, agent-readable OSV rows.
+ * @breaks  OSV API envelope drift, weak ecosystem/id validation, or silent empty rows hide vulnerability lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const OSV_BASE = "https://api.osv.dev";
+const VULN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const OSV_ECOSYSTEMS = new Set([
+  "npm",
+  "PyPI",
+  "Go",
+  "Maven",
+  "NuGet",
+  "RubyGems",
+  "crates.io",
+  "Packagist",
+  "Pub",
+  "Hex",
+  "Hackage",
+  "CRAN",
+  "Bitnami",
+  "GitHub Actions",
+  "SwiftURL",
+]);
+
+interface OsvVulnerability {
+  id?: unknown;
+  summary?: unknown;
+  aliases?: unknown[];
+  published?: unknown;
+  modified?: unknown;
+  database_specific?: {
+    severity?: unknown;
+    cwe_ids?: unknown[];
+  };
+  severity?: Array<{
+    score?: unknown;
+  }>;
+  affected?: Array<{
+    package?: {
+      ecosystem?: unknown;
+      name?: unknown;
+    };
+  }>;
+  references?: unknown[];
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function trimDate(value: unknown): string | null {
+  const text = stringField(value).trim();
+  if (!text) return null;
+  const noFraction = text.replace(/\.\d+/, "");
+  return noFraction.endsWith("Z")
+    ? noFraction
+    : text.length >= 10
+      ? text.slice(0, 10)
+      : null;
+}
+
+export function requireOsvString(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`osv ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireOsvVulnerabilityId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!id) throw new Error("osv vulnerability id is required.");
+  if (!VULN_ID_RE.test(id)) {
+    throw new Error(`osv vulnerability id "${String(value)}" is not valid.`);
+  }
+  return id;
+}
+
+export function requireOsvEcosystem(value: unknown): string {
+  const ecosystem = String(value ?? "").trim();
+  if (!ecosystem) throw new Error("osv ecosystem is required.");
+  if (!OSV_ECOSYSTEMS.has(ecosystem)) {
+    throw new Error(`osv ecosystem "${String(value)}" is not recognised.`);
+  }
+  return ecosystem;
+}
+
+export function requireOsvLimit(value: unknown, fallback = 30): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 200) {
+    throw new Error(
+      `osv limit must be an integer in [1, 200]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+function severityLabel(vuln: OsvVulnerability): string | null {
+  const dbSeverity = vuln.database_specific?.severity;
+  if (typeof dbSeverity === "string" && dbSeverity.trim())
+    return dbSeverity.trim();
+  for (const entry of Array.isArray(vuln.severity) ? vuln.severity : []) {
+    const score = stringField(entry.score).trim();
+    if (score) return score;
+  }
+  return null;
+}
+
+function aliases(vuln: OsvVulnerability): string {
+  return Array.isArray(vuln.aliases)
+    ? vuln.aliases.map(stringField).filter(Boolean).join(", ")
+    : "";
+}
+
+function affectedPackages(vuln: OsvVulnerability): string {
+  return (Array.isArray(vuln.affected) ? vuln.affected : [])
+    .map((item) => {
+      const ecosystem = stringField(item.package?.ecosystem);
+      const name = stringField(item.package?.name);
+      return ecosystem && name ? `${ecosystem}:${name}` : "";
+    })
+    .filter(Boolean)
+    .join(", ");
+}
+
+export function mapOsvQueryRows(
+  vulns: OsvVulnerability[],
+  limit: number,
+): Array<Record<string, unknown>> {
+  const sorted = vulns
+    .slice()
+    .sort((a, b) =>
+      stringField(b.published).localeCompare(stringField(a.published)),
+    )
+    .slice(0, limit);
+  return sorted.map((vuln, index) => ({
+    rank: index + 1,
+    id: stringField(vuln.id),
+    summary: stringField(vuln.summary).trim(),
+    severity: severityLabel(vuln),
+    aliases: aliases(vuln),
+    published: trimDate(vuln.published),
+    modified: trimDate(vuln.modified),
+    affectedPackages: affectedPackages(vuln),
+    url: vuln.id ? `https://osv.dev/vulnerability/${String(vuln.id)}` : "",
+  }));
+}
+
+export function mapOsvVulnerabilityRow(
+  vuln: OsvVulnerability,
+): Record<string, unknown> {
+  if (!vuln.id) throw new Error("OSV.dev returned no vulnerability record.");
+  const cwes = Array.isArray(vuln.database_specific?.cwe_ids)
+    ? vuln.database_specific.cwe_ids.map(stringField).filter(Boolean).join(", ")
+    : "";
+  return {
+    id: stringField(vuln.id),
+    summary: stringField(vuln.summary).trim(),
+    severity: severityLabel(vuln),
+    aliases: aliases(vuln),
+    published: trimDate(vuln.published),
+    modified: trimDate(vuln.modified),
+    affectedPackages: affectedPackages(vuln),
+    cwes,
+    referenceCount: Array.isArray(vuln.references) ? vuln.references.length : 0,
+    url: `https://osv.dev/vulnerability/${String(vuln.id)}`,
+  };
+}
+
+async function fetchOsvJson(
+  url: string,
+  label: string,
+  body?: unknown,
+): Promise<unknown> {
+  const response = await fetch(url, {
+    method: body === undefined ? "GET" : "POST",
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  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: "osv",
+  name: "query",
+  description: "OSV.dev vulnerabilities affecting a package",
+  domain: "osv.dev",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "package",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Package name",
+    },
+    {
+      name: "ecosystem",
+      type: "str",
+      required: true,
+      description: "OSV ecosystem",
+    },
+    {
+      name: "version",
+      type: "str",
+      description: "Specific package version",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 30,
+      description: "Max rows",
+    },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "summary",
+    "severity",
+    "aliases",
+    "published",
+    "modified",
+    "affectedPackages",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const name = requireOsvString(kwargs.package, "package");
+    const ecosystem = requireOsvEcosystem(kwargs.ecosystem);
+    const limit = requireOsvLimit(kwargs.limit);
+    const payload: Record<string, unknown> = { package: { name, ecosystem } };
+    const version = String(kwargs.version ?? "").trim();
+    if (version) payload.version = version;
+    const body = (await fetchOsvJson(
+      `${OSV_BASE}/v1/query`,
+      `osv query ${ecosystem}:${name}`,
+      payload,
+    )) as {
+      vulns?: OsvVulnerability[];
+    };
+    const vulns = Array.isArray(body.vulns) ? body.vulns : [];
+    if (vulns.length === 0) {
+      throw new Error(
+        `OSV.dev returned no vulnerabilities for ${ecosystem}:${name}.`,
+      );
+    }
+    return mapOsvQueryRows(vulns, limit);
+  },
+});
+
+cli({
+  site: "osv",
+  name: "vulnerability",
+  description: "Single OSV.dev vulnerability detail",
+  domain: "osv.dev",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "OSV vulnerability id",
+    },
+  ],
+  columns: [
+    "id",
+    "summary",
+    "severity",
+    "aliases",
+    "published",
+    "modified",
+    "affectedPackages",
+    "cwes",
+    "referenceCount",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireOsvVulnerabilityId(kwargs.id);
+    const vuln = (await fetchOsvJson(
+      `${OSV_BASE}/v1/vulns/${encodeURIComponent(id)}`,
+      `osv vulnerability ${id}`,
+    )) as OsvVulnerability;
+    return [mapOsvVulnerabilityRow(vuln)];
+  },
+});

package/src/adapters/packagist/package.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapPackagistPackageRow,
+  pickStableVersion,
+  requirePackagistName,
+} from "./package.js";
+
+describe("packagist agent-facing package command", () => {
+  it("validates package names and picks stable versions", () => {
+    expect(requirePackagistName(" Symfony/Console ")).toBe("symfony/console");
+    expect(() => requirePackagistName("symfony")).toThrow(
+      'must be "<vendor>/<package>"',
+    );
+    expect(
+      pickStableVersion({
+        "dev-main": {},
+        "2.0.0-RC1": {},
+        "1.9.0": {},
+      }),
+    ).toBe("1.9.0");
+  });
+
+  it("maps package metadata and download counters", () => {
+    expect(
+      mapPackagistPackageRow(
+        {
+          package: {
+            name: "symfony/console",
+            description: "Console tools",
+            repository: "https://github.com/symfony/console",
+            github_stars: 42,
+            favers: 7,
+            downloads: { total: 1000, monthly: 100, daily: 10 },
+            versions: {
+              "1.0.0": {
+                time: "2020-01-01T00:00:00+00:00",
+                license: ["MIT"],
+              },
+            },
+          },
+        },
+        "symfony/console",
+      ),
+    ).toEqual({
+      package: "symfony/console",
+      version: "1.0.0",
+      releasedAt: "2020-01-01",
+      license: "MIT",
+      description: "Console tools",
+      repository: "https://github.com/symfony/console",
+      githubStars: 42,
+      favers: 7,
+      downloads: 1000,
+      monthlyDownloads: 100,
+      dailyDownloads: 10,
+      url: "https://packagist.org/packages/symfony/console",
+    });
+    expect(() => mapPackagistPackageRow({}, "missing/pkg")).toThrow(
+      "returned no package metadata",
+    );
+  });
+});

package/src/adapters/packagist/package.ts

@@ -0,0 +1,146 @@
+/**
+ * @owner   src/adapters/packagist/package.ts
+ * @does    Register agent-facing Packagist single-package metadata command.
+ * @needs   packagist.org package JSON API and stable-version selection.
+ * @feeds   surface coverage ledger, PHP dependency inspection, registry command surface.
+ * @breaks  Packagist envelope drift or unstable version picking hides Composer package state.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const PACKAGIST_BASE = "https://packagist.org";
+
+interface PackagistPackage {
+  name?: unknown;
+  description?: unknown;
+  repository?: unknown;
+  github_stars?: unknown;
+  favers?: unknown;
+  downloads?: {
+    total?: unknown;
+    monthly?: unknown;
+    daily?: unknown;
+  };
+  versions?: Record<string, { time?: unknown; license?: unknown }>;
+}
+
+interface PackagistBody {
+  package?: PackagistPackage;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function numberField(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function requirePackagistName(value: unknown): string {
+  const name = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/.test(name)) {
+    throw new Error('packagist package name must be "<vendor>/<package>".');
+  }
+  return name;
+}
+
+export function pickStableVersion(
+  versions: PackagistPackage["versions"],
+): string {
+  const keys = Object.keys(versions ?? {});
+  return (
+    keys.find(
+      (version) =>
+        /^v?\d+\.\d+\.\d+(?:\+\S+)?$/.test(version) &&
+        !/dev|alpha|beta|rc/i.test(version),
+    ) ??
+    keys.find((version) => !/dev|alpha|beta|rc/i.test(version)) ??
+    keys[0] ??
+    ""
+  );
+}
+
+export function mapPackagistPackageRow(
+  body: PackagistBody,
+  requested: string,
+): Record<string, unknown> {
+  const pkg = body.package;
+  if (!pkg || typeof pkg !== "object") {
+    throw new Error(`Packagist returned no package metadata for ${requested}.`);
+  }
+  const version = pickStableVersion(pkg.versions);
+  const entry = version ? pkg.versions?.[version] : undefined;
+  const license = Array.isArray(entry?.license)
+    ? entry.license.map(stringField).filter(Boolean).join(", ")
+    : "";
+  const downloads = pkg.downloads ?? {};
+  const name = stringField(pkg.name) || requested;
+  return {
+    package: name,
+    version,
+    releasedAt: stringField(entry?.time).slice(0, 10),
+    license,
+    description: stringField(pkg.description),
+    repository: stringField(pkg.repository),
+    githubStars: numberField(pkg.github_stars),
+    favers: numberField(pkg.favers),
+    downloads: numberField(downloads.total),
+    monthlyDownloads: numberField(downloads.monthly),
+    dailyDownloads: numberField(downloads.daily),
+    url: `${PACKAGIST_BASE}/packages/${name}`,
+  };
+}
+
+async function fetchPackagistJson(name: string): Promise<unknown> {
+  const response = await fetch(`${PACKAGIST_BASE}/packages/${name}.json`, {
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (response.status === 404)
+    throw new Error(`packagist package ${name} returned no result.`);
+  if (!response.ok)
+    throw new Error(
+      `packagist package ${name} returned HTTP ${response.status}.`,
+    );
+  return response.json();
+}
+
+cli({
+  site: "packagist",
+  name: "package",
+  description: "Fetch Packagist package metadata",
+  domain: "packagist.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "name",
+      type: "str",
+      required: true,
+      positional: true,
+      description: 'Composer package "<vendor>/<package>"',
+    },
+  ],
+  columns: [
+    "package",
+    "version",
+    "releasedAt",
+    "license",
+    "description",
+    "repository",
+    "githubStars",
+    "favers",
+    "downloads",
+    "monthlyDownloads",
+    "dailyDownloads",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const name = requirePackagistName(kwargs.name);
+    const body = (await fetchPackagistJson(name)) as PackagistBody;
+    return [mapPackagistPackageRow(body, name)];
+  },
+});

package/src/adapters/pubmed/articles.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapPubMedArticleRows,
+  mapPubMedSummaryRows,
+  requirePmid,
+  requirePubMedLimit,
+  requirePubMedText,
+} from "./articles.js";
+
+describe("pubmed agent-facing commands", () => {
+  it("validates PubMed inputs", () => {
+    expect(requirePubMedText(" cancer ", "query")).toBe("cancer");
+    expect(() => requirePubMedText("", "query")).toThrow("cannot be empty");
+    expect(requirePmid("37780221")).toBe("37780221");
+    expect(() => requirePmid("PMID:1")).toThrow("numeric PMID");
+    expect(requirePubMedLimit(undefined)).toBe(20);
+    expect(requirePubMedLimit("100")).toBe(100);
+    expect(() => requirePubMedLimit("0")).toThrow("pubmed limit must");
+  });
+
+  it("maps PubMed summary rows in PMID order", () => {
+    expect(
+      mapPubMedSummaryRows(
+        [
+          {
+            uid: "2",
+            title: "Second",
+            authors: [
+              { name: "Ada" },
+              { name: "Grace" },
+              { name: "Linus" },
+              { name: "Ken" },
+            ],
+            source: "Journal",
+            pubdate: "2026 May",
+            pubtype: ["Journal Article"],
+            articleids: [{ idtype: "doi", value: "10.1/example" }],
+          },
+          {
+            uid: "1",
+            title: "First",
+            authors: [{ lastname: "Hopper", initials: "G" }],
+            source: "Other",
+            pubdate: "2025",
+            pubtype: ["Review"],
+            articleids: [],
+          },
+        ],
+        ["1", "2"],
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        pmid: "1",
+        title: "First",
+        authors: "Hopper G",
+        year: "2025",
+        article_type: "Review",
+      },
+      {
+        rank: 2,
+        pmid: "2",
+        authors: "Ada, Grace, Linus, et al.",
+        doi: "10.1/example",
+      },
+    ]);
+  });
+
+  it("maps PubMed article XML rows", () => {
+    const rows = mapPubMedArticleRows(
+      `
+      <PubmedArticle>
+        <ArticleTitle>Test &amp; Treat</ArticleTitle>
+        <Abstract><AbstractText>Long abstract</AbstractText></Abstract>
+        <Author><LastName>Ada</LastName></Author>
+        <Journal><Title>Journal</Title></Journal>
+        <PubDate><Year>2026</Year></PubDate>
+        <PublicationType>Journal Article</PublicationType>
+        <Language>eng</Language>
+        <ArticleId IdType="doi">10.1/example</ArticleId>
+      </PubmedArticle>
+      `,
+      "123",
+    );
+    expect(rows).toContainEqual({ field: "PMID", value: "123" });
+    expect(rows).toContainEqual({ field: "Title", value: "Test & Treat" });
+    expect(rows).toContainEqual({ field: "DOI", value: "10.1/example" });
+    expect(rows).toContainEqual({
+      field: "URL",
+      value: "https://pubmed.ncbi.nlm.nih.gov/123/",
+    });
+    expect(() => mapPubMedArticleRows("<root />", "123")).toThrow(
+      "did not include a title",
+    );
+  });
+});