@zenalexa/unicli 0.218.1 → 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/info.yaml

@@ -0,0 +1,34 @@
+# @owner   src/adapters/packagist/info.yaml
+# @does    Fetch Packagist Composer package metadata by vendor/package name.
+# @needs   packagist.org package API
+# @feeds   unicli packagist info, package registry expansion
+# @breaks  Agents cannot inspect PHP package metadata and maintainers.
+site: packagist
+name: info
+description: Get Packagist Composer package metadata
+type: web-api
+domain: packagist.org
+strategy: public
+args:
+  package:
+    type: str
+    required: true
+    positional: true
+    description: Composer package name, for example laravel/framework
+pipeline:
+  - fetch:
+      url: "https://packagist.org/packages/${{ args.package }}.json"
+  - select: package
+  - map:
+      name: "${{ item.name }}"
+      description: "${{ item.description }}"
+      time: "${{ item.time }}"
+      repository: "${{ item.repository }}"
+      versions: "${{ item.versions | keys | length }}"
+columns: [name, description, time, repository, versions]
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

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

@@ -0,0 +1,41 @@
+# @owner   src/adapters/packagist/search.yaml
+# @does    Search Packagist Composer packages through the public JSON API.
+# @needs   packagist.org search API
+# @feeds   unicli packagist search, package registry expansion
+# @breaks  PHP package discovery loses first-class CLI coverage.
+site: packagist
+name: search
+description: Search Packagist Composer packages
+type: web-api
+domain: packagist.org
+strategy: public
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Composer package search query
+  limit:
+    type: int
+    default: 20
+pipeline:
+  - fetch:
+      url: "https://packagist.org/search.json"
+      params:
+        q: "${{ args.query }}"
+        per_page: "${{ args.limit }}"
+  - select: results
+  - map:
+      name: "${{ item.name }}"
+      description: "${{ (item.description || '') | truncate(80) }}"
+      downloads: "${{ item.downloads }}"
+      favers: "${{ item.favers }}"
+      url: "${{ item.url }}"
+  - limit: ${{ args.limit }}
+columns: [name, description, downloads, favers, url]
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/pexels/search.yaml

@@ -4,6 +4,7 @@ description: Search free stock photos on Pexels
 type: web-api
 domain: api.pexels.com
 strategy: header
+lint_listing_detail: skip
 args:
   query:
     required: true

package/src/adapters/pinduoduo/hot.yaml

@@ -4,6 +4,7 @@ description: Pinduoduo hot/trending products
 type: web-api
 domain: mobile.yangkeduo.com
 strategy: cookie
+lint_listing_detail: skip
 args:
   limit:
     required: false

package/src/adapters/pinduoduo/search.yaml

@@ -4,6 +4,7 @@ description: Search Pinduoduo products
 domain: mobile.yangkeduo.com
 type: web-api
 strategy: cookie
+lint_listing_detail: skip
 
 args:
   query:

package/src/adapters/powerpoint/list.yaml

@@ -3,6 +3,7 @@ name: list
 description: List open Microsoft PowerPoint presentations
 type: desktop
 strategy: public
+lint_listing_detail: skip
 binary: osascript
 detect: "test $(uname) = Darwin"
 

package/src/adapters/producthunt/browse.yaml

@@ -4,6 +4,7 @@ description: Browse Product Hunt products by category
 domain: www.producthunt.com
 type: web-api
 strategy: public
+lint_listing_detail: skip
 
 args:
   topic:

package/src/adapters/producthunt/hot.yaml

@@ -4,6 +4,7 @@ description: ProductHunt trending products (RSS)
 domain: www.producthunt.com
 type: web-api
 strategy: public
+lint_listing_detail: skip
 
 args:
   limit:

package/src/adapters/producthunt/search.yaml

@@ -4,6 +4,7 @@ description: Search Product Hunt products
 type: web-api
 domain: www.producthunt.com
 strategy: public
+lint_listing_detail: skip
 
 args:
   query:

package/src/adapters/pub-dev/info.yaml

@@ -0,0 +1,34 @@
+# @owner   src/adapters/pub-dev/info.yaml
+# @does    Fetch Dart and Flutter package metadata by pub.dev package name.
+# @needs   pub.dev package API
+# @feeds   unicli pub-dev info, package registry expansion
+# @breaks  Agents cannot inspect Dart package version and repository metadata.
+site: pub-dev
+name: info
+description: Get Dart and Flutter package metadata from pub.dev
+type: web-api
+domain: pub.dev
+strategy: public
+args:
+  package:
+    type: str
+    required: true
+    positional: true
+    description: pub.dev package name, for example http
+pipeline:
+  - fetch:
+      url: "https://pub.dev/api/packages/${{ args.package | urlencode }}"
+  - map:
+      name: "${{ item.name }}"
+      version: "${{ item.latest.version }}"
+      description: "${{ item.latest.pubspec.description || '' }}"
+      repository: "${{ item.latest.pubspec.repository || '' }}"
+      homepage: "${{ item.latest.pubspec.homepage || '' }}"
+      versions: "${{ item.versions | length }}"
+columns: [name, version, description, repository, homepage, versions]
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2