@zenalexa/unicli 0.218.1 → 0.220.0

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/nytimes/search.yaml

@@ -4,6 +4,7 @@ description: Search NYTimes articles
 domain: api.nytimes.com
 type: web-api
 strategy: public
+lint_listing_detail: skip
 
 args:
   query:

package/src/adapters/nytimes/top.yaml

@@ -4,6 +4,7 @@ description: New York Times top stories via RSS
 type: web-api
 domain: rss.nytimes.com
 strategy: public
+lint_listing_detail: skip
 args:
   section:
     required: false

package/src/adapters/obs/stream-start.yaml

@@ -3,6 +3,7 @@ site: obs
 name: stream-start
 description: Start OBS streaming
 type: service
+lint_listing_detail: skip
 
 args:
   port:

package/src/adapters/obs/stream-stop.yaml

@@ -3,6 +3,7 @@ site: obs
 name: stream-stop
 description: Stop OBS streaming
 type: service
+lint_listing_detail: skip
 
 args:
   port:

package/src/adapters/obsidian/search.yaml

@@ -6,6 +6,7 @@ type: desktop
 binary: open
 detect: Darwin
 strategy: public
+lint_listing_detail: skip
 
 args:
   vault:

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,
+    });
+  });
+});

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/ollama/list.yaml

@@ -3,6 +3,7 @@ site: ollama
 name: list
 description: List locally installed Ollama models
 type: service
+lint_listing_detail: skip
 base: "http://localhost:11434"
 health: /api/tags