@zenalexa/unicli 0.218.1 → 0.220.0

package/src/adapters/mubu/search.yaml

@@ -3,6 +3,7 @@ name: search
 description: Search Mubu notes
 domain: mubu.com
 strategy: intercept
+lint_listing_detail: skip
 browser: true
 
 args:

package/src/adapters/netease-music/hot.yaml

@@ -4,6 +4,7 @@ description: NetEase Cloud Music hot/trending songs
 type: web-api
 domain: music.163.com
 strategy: public
+lint_listing_detail: skip
 args:
   limit:
     required: false

package/src/adapters/netease-music/search.yaml

@@ -4,6 +4,7 @@ description: Search songs on NetEase Cloud Music
 type: web-api
 domain: music.163.com
 strategy: public
+lint_listing_detail: skip
 args:
   query:
     required: true

package/src/adapters/netease-music/top.yaml

@@ -4,6 +4,7 @@ description: NetEase Cloud Music top charts
 domain: music.163.com
 type: web-api
 strategy: public
+lint_listing_detail: skip
 
 args:
   id:

package/src/adapters/notion/search.yaml

@@ -4,6 +4,7 @@ description: Search Notion pages via web API
 domain: www.notion.so
 type: web-api
 strategy: cookie
+lint_listing_detail: skip
 
 args:
   query:

package/src/adapters/npm/package.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { mapNpmPackageRow, requireNpmPackageName } from "./package.js";
+
+describe("npm agent-facing package command", () => {
+  it("validates npm package names", () => {
+    expect(requireNpmPackageName(" @vercel/og ")).toBe("@vercel/og");
+    expect(requireNpmPackageName("react")).toBe("react");
+    expect(() => requireNpmPackageName("")).toThrow("is required");
+    expect(() => requireNpmPackageName("../react")).toThrow("not valid");
+  });
+
+  it("maps latest package metadata to agent-facing columns", () => {
+    expect(
+      mapNpmPackageRow(
+        {
+          name: "react",
+          description: "base description",
+          "dist-tags": { latest: "19.0.0" },
+          versions: {
+            "19.0.0": {
+              description: "ui library",
+              license: { type: "MIT" },
+              homepage: "https://react.dev",
+              repository: { url: "git+https://github.com/facebook/react.git" },
+              bugs: { url: "https://github.com/facebook/react/issues" },
+              keywords: ["ui", "react"],
+            },
+          },
+          maintainers: [{ name: "core" }, { email: "ops@example.test" }],
+          time: {
+            created: "2011-10-26T00:00:00.000Z",
+            modified: "2026-05-01T00:00:00.000Z",
+          },
+        },
+        "react",
+      ),
+    ).toMatchObject({
+      name: "react",
+      latestVersion: "19.0.0",
+      description: "ui library",
+      license: "MIT",
+      repository: "https://github.com/facebook/react",
+      bugs: "https://github.com/facebook/react/issues",
+      maintainers: "core, ops@example.test",
+      keywords: "ui, react",
+      created: "2011-10-26",
+      modified: "2026-05-01",
+    });
+    expect(() => mapNpmPackageRow({}, "missing")).toThrow(
+      "has no latest version",
+    );
+  });
+});

package/src/adapters/npm/package.ts

@@ -0,0 +1,177 @@
+/**
+ * @owner   src/adapters/npm/package.ts
+ * @does    Register agent-facing npm single-package metadata command.
+ * @needs   registry.npmjs.org public package documents.
+ * @feeds   surface coverage ledger, JavaScript package inspection, registry command surface.
+ * @breaks  npm registry document drift or weak scoped-name parsing hides package metadata failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const NPM_REGISTRY = "https://registry.npmjs.org";
+
+interface NpmPackageVersion {
+  description?: unknown;
+  license?: unknown;
+  homepage?: unknown;
+  repository?: unknown;
+  bugs?: unknown;
+  keywords?: unknown;
+}
+
+interface NpmPackageBody {
+  name?: unknown;
+  description?: unknown;
+  "dist-tags"?: { latest?: unknown };
+  versions?: Record<string, NpmPackageVersion>;
+  maintainers?: unknown;
+  time?: { created?: unknown; modified?: unknown };
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function requireNpmPackageName(value: unknown): string {
+  const name = String(value ?? "").trim();
+  if (!name) throw new Error("npm package name is required.");
+  if (
+    !/^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i.test(name) ||
+    name.includes("..")
+  ) {
+    throw new Error(`npm package name "${String(value)}" is not valid.`);
+  }
+  return name;
+}
+
+function repoUrl(repo: unknown): string {
+  if (typeof repo === "string")
+    return repo.replace(/^git\+/, "").replace(/\.git$/, "");
+  if (
+    repo &&
+    typeof repo === "object" &&
+    typeof (repo as { url?: unknown }).url === "string"
+  ) {
+    return (repo as { url: string }).url
+      .replace(/^git\+/, "")
+      .replace(/\.git$/, "");
+  }
+  return "";
+}
+
+function bugUrl(bugs: unknown): string {
+  if (typeof bugs === "string") return bugs;
+  if (
+    bugs &&
+    typeof bugs === "object" &&
+    typeof (bugs as { url?: unknown }).url === "string"
+  ) {
+    return (bugs as { url: string }).url;
+  }
+  return "";
+}
+
+function licenseText(license: unknown): string {
+  if (typeof license === "string") return license.trim();
+  if (
+    license &&
+    typeof license === "object" &&
+    typeof (license as { type?: unknown }).type === "string"
+  ) {
+    return (license as { type: string }).type.trim();
+  }
+  return "";
+}
+
+export function mapNpmPackageRow(
+  body: NpmPackageBody,
+  requested: string,
+): Record<string, unknown> {
+  const latest = stringField(body["dist-tags"]?.latest);
+  if (!latest) {
+    throw new Error(`npm registry has no latest version for "${requested}".`);
+  }
+  const version = body.versions?.[latest] ?? {};
+  const name = stringField(body.name) || requested;
+  const maintainers = Array.isArray(body.maintainers)
+    ? body.maintainers
+        .map((item) => {
+          if (item && typeof item === "object") {
+            const rec = item as { name?: unknown; email?: unknown };
+            return stringField(rec.name) || stringField(rec.email);
+          }
+          return String(item ?? "").trim();
+        })
+        .filter(Boolean)
+        .join(", ")
+    : "";
+  const keywords = Array.isArray(version.keywords)
+    ? version.keywords.map(stringField).filter(Boolean).join(", ")
+    : "";
+  return {
+    name,
+    latestVersion: latest,
+    description:
+      stringField(version.description) || stringField(body.description),
+    license: licenseText(version.license),
+    homepage: stringField(version.homepage),
+    repository: repoUrl(version.repository),
+    bugs: bugUrl(version.bugs),
+    maintainers,
+    keywords,
+    created: stringField(body.time?.created).slice(0, 10),
+    modified: stringField(body.time?.modified).slice(0, 10),
+    url: `https://www.npmjs.com/package/${encodeURIComponent(name)}`,
+  };
+}
+
+async function fetchNpmJson(name: string): Promise<unknown> {
+  const path = name.split("/").map(encodeURIComponent).join("/");
+  const response = await fetch(`${NPM_REGISTRY}/${path}`, {
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (response.status === 404)
+    throw new Error(`npm package ${name} returned no result.`);
+  if (!response.ok)
+    throw new Error(`npm package ${name} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "npm",
+  name: "package",
+  description: "Single npm package metadata",
+  domain: "registry.npmjs.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "name",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "npm package name",
+    },
+  ],
+  columns: [
+    "name",
+    "latestVersion",
+    "description",
+    "license",
+    "homepage",
+    "repository",
+    "bugs",
+    "maintainers",
+    "keywords",
+    "created",
+    "modified",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const name = requireNpmPackageName(kwargs.name);
+    const body = (await fetchNpmJson(name)) as NpmPackageBody;
+    return [mapNpmPackageRow(body, name)];
+  },
+});

package/src/adapters/npm-trends/trending.yaml

@@ -4,6 +4,7 @@ description: Get trending npm packages
 type: web-api
 domain: npmtrends.com
 strategy: public
+lint_listing_detail: skip
 
 pipeline:
   - fetch:

package/src/adapters/nuget/info.yaml

@@ -0,0 +1,41 @@
+# @owner   src/adapters/nuget/info.yaml
+# @does    Fetch top NuGet package metadata for a package id query.
+# @needs   azuresearch-usnc.nuget.org query API
+# @feeds   unicli nuget info, package registry expansion
+# @breaks  Agents cannot inspect .NET package version and download metadata.
+site: nuget
+name: info
+description: Get NuGet package metadata
+type: web-api
+domain: nuget.org
+strategy: public
+args:
+  package:
+    type: str
+    required: true
+    positional: true
+    description: NuGet package id, for example Newtonsoft.Json
+pipeline:
+  - fetch:
+      url: "https://azuresearch-usnc.nuget.org/query"
+      params:
+        q: "packageid:${{ args.package }}"
+        take: "1"
+        prerelease: "false"
+        semVerLevel: "2.0.0"
+  - select: data
+  - map:
+      name: "${{ item.id }}"
+      version: "${{ item.version }}"
+      description: "${{ item.description }}"
+      downloads: "${{ item.totalDownloads }}"
+      project: "${{ item.projectUrl }}"
+      verified: "${{ item.verified }}"
+  - limit: 1
+columns: [name, version, description, downloads, project, verified]
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/nuget/package.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import {
+  collectNugetEntries,
+  mapNugetPackageRows,
+  requireNugetPackageId,
+} from "./package.js";
+
+describe("nuget agent-facing package command", () => {
+  it("validates package ids", () => {
+    expect(requireNugetPackageId(" Newtonsoft.Json ")).toBe("Newtonsoft.Json");
+    expect(() => requireNugetPackageId("../Newtonsoft.Json")).toThrow(
+      "package id must be",
+    );
+  });
+
+  it("collects inline and stub registration pages", async () => {
+    await expect(
+      collectNugetEntries(
+        {
+          items: [
+            {
+              items: [
+                {
+                  catalogEntry: {
+                    id: "Pkg",
+                    version: "1.0.0",
+                    published: "2020-01-01T00:00:00Z",
+                  },
+                },
+              ],
+            },
+            { "@id": "https://example.test/page.json" },
+          ],
+        },
+        async () => ({
+          items: [
+            {
+              catalogEntry: {
+                id: "Pkg",
+                version: "2.0.0",
+                published: "2021-01-01T00:00:00Z",
+              },
+            },
+          ],
+        }),
+      ),
+    ).resolves.toHaveLength(2);
+
+    await expect(
+      collectNugetEntries({ items: [{}] }, async () => ({})),
+    ).rejects.toThrow("missing @id");
+  });
+
+  it("maps version history rows sorted by published desc", () => {
+    expect(
+      mapNugetPackageRows(
+        [
+          {
+            catalogEntry: {
+              id: "Newtonsoft.Json",
+              version: "1.0.0",
+              title: "JSON",
+              authors: ["A", "B"],
+              tags: ["json", "dotnet"],
+              language: "en",
+              licenseExpression: "MIT",
+              projectUrl: "https://example.test",
+              published: "2020-01-01T00:00:00Z",
+              listed: true,
+            },
+          },
+          {
+            catalogEntry: {
+              id: "Newtonsoft.Json",
+              version: "2.0.0",
+              published: "2021-01-01T00:00:00Z",
+            },
+          },
+        ],
+        "Newtonsoft.Json",
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        id: "Newtonsoft.Json",
+        version: "2.0.0",
+        published: "2021-01-01T00:00:00Z",
+      },
+      {
+        rank: 2,
+        id: "Newtonsoft.Json",
+        version: "1.0.0",
+        authors: "A, B",
+        tags: "json, dotnet",
+        listed: true,
+      },
+    ]);
+    expect(() => mapNugetPackageRows([], "missing")).toThrow(
+      "No published versions",
+    );
+  });
+});

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

@@ -0,0 +1,43 @@
+# @owner   src/adapters/nuget/search.yaml
+# @does    Search NuGet packages through the public V3 search endpoint.
+# @needs   azuresearch-usnc.nuget.org query API
+# @feeds   unicli nuget search, package registry expansion
+# @breaks  .NET package discovery loses first-class CLI coverage.
+site: nuget
+name: search
+description: Search NuGet packages
+type: web-api
+domain: nuget.org
+strategy: public
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Package search query
+  limit:
+    type: int
+    default: 20
+pipeline:
+  - fetch:
+      url: "https://azuresearch-usnc.nuget.org/query"
+      params:
+        q: "${{ args.query }}"
+        take: "${{ args.limit }}"
+        prerelease: "false"
+        semVerLevel: "2.0.0"
+  - select: data
+  - map:
+      name: "${{ item.id }}"
+      version: "${{ item.version }}"
+      description: "${{ (item.description || '') | truncate(80) }}"
+      downloads: "${{ item.totalDownloads }}"
+      verified: "${{ item.verified }}"
+  - limit: ${{ args.limit }}
+columns: [name, version, description, downloads, verified]
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2