@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/moegirl/web.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import {
+  mapMoegirlOpenSearch,
+  parseMoegirlLinksHtml,
+  parseMoegirlPageHtml,
+} from "./web.js";
+
+describe("moegirl public commands", () => {
+  it("registers search, page, and links", () => {
+    expect(
+      Object.keys(resolveCommand("moegirl", "search")!.adapter.commands),
+    ).toEqual(expect.arrayContaining(["search", "page", "links"]));
+  });
+
+  it("maps OpenSearch results", () => {
+    expect(
+      mapMoegirlOpenSearch(
+        [
+          "花火",
+          ["花火", "花火(星穹铁道)"],
+          ["", ""],
+          [
+            "https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB",
+            "https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB(%E6%98%9F%E7%A9%B9%E9%93%81%E9%81%93)",
+          ],
+        ],
+        5,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        title: "花火",
+        description: "",
+        url: "https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB",
+      },
+      {
+        rank: 2,
+        title: "花火(星穹铁道)",
+        description: "",
+        url: "https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB(%E6%98%9F%E7%A9%B9%E9%93%81%E9%81%93)",
+      },
+    ]);
+  });
+
+  it("parses page text and metadata", () => {
+    const row = parseMoegirlPageHtml(
+      `<title>花火(星穹铁道) - 萌娘百科 万物皆可萌的百科全书</title>
+       <meta name="description" content="花火是游戏《崩坏：星穹铁道》中的登场角色。">
+       <link rel="canonical" href="https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB(%E6%98%9F%E7%A9%B9%E9%93%81%E9%81%93)">
+       <script>RLCONF={"wgCategories":["崩坏：星穹铁道角色","游戏角色"]};</script>
+       <template id="MOE_SKIN_TEMPLATE_BODYCONTENT"><div class="mw-parser-output">
+       <p><b>花火</b>是游戏《崩坏：星穹铁道》中的角色。</p>
+       <p>她属于假面愚者。</p></div></template>`,
+      "花火(星穹铁道)",
+      1,
+    );
+    expect(row).toMatchObject({
+      title: "花火(星穹铁道)",
+      description: "花火是游戏《崩坏：星穹铁道》中的登场角色。",
+      categories: ["崩坏：星穹铁道角色", "游戏角色"],
+      paragraphs: 1,
+      url: "https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB(%E6%98%9F%E7%A9%B9%E9%93%81%E9%81%93)",
+    });
+    expect(String(row.extract)).toContain("崩坏：星穹铁道");
+  });
+
+  it("extracts disambiguation links with contains filter", () => {
+    expect(
+      parseMoegirlLinksHtml(
+        `<template id="MOE_SKIN_TEMPLATE_BODYCONTENT"><div>
+          <a href="/%E8%8A%B1%E7%81%AB" title="花火">花火</a>
+          <a href="/%E8%8A%B1%E7%81%AB(%E6%98%9F%E7%A9%B9%E9%93%81%E9%81%93)" title="花火(星穹铁道)">花火(星穹铁道)</a>
+          <a href="/index.php?title=X&amp;action=edit&amp;redlink=1" title="X（页面不存在）">X</a>
+        </div></template>`,
+        5,
+        "星穹铁道",
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        title: "花火(星穹铁道)",
+        url: "https://zh.moegirl.org.cn/%E8%8A%B1%E7%81%AB(%E6%98%9F%E7%A9%B9%E9%93%81%E9%81%93)",
+      },
+    ]);
+  });
+});

package/src/adapters/moegirl/web.ts

@@ -0,0 +1,343 @@
+/**
+ * @owner   src/adapters/moegirl/web.ts
+ * @does    Register Moegirl public search, page reading, and article link extraction commands.
+ * @needs   Moegirl public OpenSearch endpoint and rendered MediaWiki HTML.
+ * @feeds   ACG entity discovery, character disambiguation, and wiki-backed content research.
+ * @breaks  Moegirl skin/template markup drift can reduce page and link extraction quality.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const ORIGIN = "https://zh.moegirl.org.cn";
+
+interface SearchRow {
+  rank: number;
+  title: string;
+  description: string;
+  url: string;
+}
+
+interface LinkRow {
+  rank: number;
+  title: string;
+  url: string;
+}
+
+function str(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function decodeHtml(value: unknown): string {
+  return decodeHtmlEntities(value).replace(/\s+/g, " ").trim();
+}
+
+function decodeHtmlText(value: unknown): string {
+  return decodeHtmlEntities(value)
+    .replace(/[ \t\f\v]+/g, " ")
+    .replace(/\n[ \t]+/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function decodeHtmlEntities(value: unknown): string {
+  return str(value)
+    .replace(/&#(\d+);/g, (_m, code: string) =>
+      String.fromCodePoint(Number(code)),
+    )
+    .replace(/&#x([0-9a-f]+);/gi, (_m, code: string) =>
+      String.fromCodePoint(Number.parseInt(code, 16)),
+    )
+    .replace(/ /g, " ")
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#039;/g, "'")
+    .replace(/&#39;/g, "'");
+}
+
+function requireText(value: unknown, label: string): string {
+  const text = str(value).trim();
+  if (!text) throw new Error(`moegirl ${label} cannot be empty.`);
+  return text;
+}
+
+function requireLimit(value: unknown, fallback = 10): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 50) {
+    throw new Error("moegirl limit must be an integer in [1, 50].");
+  }
+  return n;
+}
+
+function requireParagraphCap(value: unknown): number {
+  if (value === undefined || value === null || value === "") return 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0 || n > 100) {
+    throw new Error("moegirl paragraphs must be an integer in [0, 100].");
+  }
+  return n;
+}
+
+function articleUrl(title: string): string {
+  return `${ORIGIN}/${encodeURIComponent(title.replace(/ /g, "_"))}`;
+}
+
+async function fetchJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`moegirl request failed with HTTP ${response.status}.`);
+  }
+  return response.json();
+}
+
+async function fetchText(url: string): Promise<string> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "text/html,application/xhtml+xml",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`moegirl request failed with HTTP ${response.status}.`);
+  }
+  return response.text();
+}
+
+export function mapMoegirlOpenSearch(
+  data: unknown,
+  limit: number,
+): SearchRow[] {
+  if (
+    !Array.isArray(data) ||
+    !Array.isArray(data[1]) ||
+    !Array.isArray(data[3])
+  ) {
+    throw new Error("moegirl OpenSearch response shape changed.");
+  }
+  const titles = data[1] as unknown[];
+  const descriptions = Array.isArray(data[2]) ? (data[2] as unknown[]) : [];
+  const urls = data[3] as unknown[];
+  return titles.slice(0, limit).map((title, index) => ({
+    rank: index + 1,
+    title: str(title),
+    description: str(descriptions[index]),
+    url: str(urls[index]),
+  }));
+}
+
+function firstMatch(value: string, re: RegExp): string {
+  const match = value.match(re);
+  return match ? decodeHtml(match[1]) : "";
+}
+
+function bodyHtml(html: string): string {
+  return (
+    firstRawMatch(
+      html,
+      /<template id="MOE_SKIN_TEMPLATE_BODYCONTENT">([\s\S]*?)<\/template>/,
+    ) ||
+    firstRawMatch(
+      html,
+      /<div[^>]+class="[^"]*\bmw-parser-output\b[^"]*"[^>]*>([\s\S]*?)<\/div>\s*<\/div>/,
+    ) ||
+    html
+  );
+}
+
+function firstRawMatch(value: string, re: RegExp): string {
+  const match = value.match(re);
+  return match ? match[1] : "";
+}
+
+function cleanArticleText(html: string): string {
+  return decodeHtmlText(
+    bodyHtml(html)
+      .replace(/<style[\s\S]*?<\/style>/gi, " ")
+      .replace(/<script[\s\S]*?<\/script>/gi, " ")
+      .replace(/<sup[\s\S]*?<\/sup>/gi, " ")
+      .replace(/<\/(?:p|li|h[1-6]|tr)>/gi, "\n\n")
+      .replace(/<(?:br|div)\b[^>]*>/gi, "\n")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/\n\s+/g, "\n")
+      .replace(/\n{3,}/g, "\n\n"),
+  );
+}
+
+export function parseMoegirlPageHtml(
+  html: string,
+  requestedTitle: string,
+  paragraphCap: number,
+): Record<string, unknown> {
+  const pageTitle =
+    firstMatch(html, /<title>([^<]+?)(?: - 萌娘百科[^<]*)?<\/title>/) ||
+    firstMatch(
+      html,
+      /<meta property="og:title" content="(?:&lt;[^&]+&gt;)?([^"<]+)(?:&lt;\/[^&]+&gt;)?"/,
+    ) ||
+    requestedTitle;
+  const title = requestedTitle.includes("(") ? requestedTitle : pageTitle;
+  const description =
+    firstMatch(html, /<meta name="description" content="([^"]*)"/) ||
+    firstMatch(html, /<meta property="og:description" content="([^"]*)"/);
+  const url =
+    firstMatch(html, /<link rel="canonical" href="([^"]+)"/) ||
+    articleUrl(title);
+  const categories = [...html.matchAll(/"wgCategories":\[(.*?)\]/g)][0]?.[1]
+    ?.split(",")
+    .map((item) => decodeHtml(item.replace(/^"|"$/g, "")))
+    .filter(Boolean);
+  const text = cleanArticleText(html);
+  if (!text) {
+    throw new Error(
+      `Moegirl article "${requestedTitle}" has no readable text.`,
+    );
+  }
+  const paragraphs = text
+    .split(/\n+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  const selected =
+    paragraphCap > 0 ? paragraphs.slice(0, paragraphCap) : paragraphs;
+  return {
+    title,
+    description,
+    categories: categories ?? [],
+    paragraphs: selected.length,
+    extract: selected.join("\n\n"),
+    url,
+  };
+}
+
+export function parseMoegirlLinksHtml(
+  html: string,
+  limit: number,
+  contains: string,
+): LinkRow[] {
+  const rows: LinkRow[] = [];
+  const seen = new Set<string>();
+  const needle = contains.trim();
+  for (const match of bodyHtml(html).matchAll(
+    /<a\b(?=[^>]*\bhref="([^"]+)")(?=[^>]*\btitle="([^"]+)")[^>]*>/g,
+  )) {
+    const href = decodeHtml(match[1]);
+    const title = decodeHtml(match[2]);
+    if (!href.startsWith("/") || href.includes("redlink=1")) continue;
+    if (title.includes("页面不存在")) continue;
+    if (needle && !title.includes(needle)) continue;
+    const key = `${title}\n${href}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    rows.push({
+      rank: rows.length + 1,
+      title,
+      url: `${ORIGIN}${href}`,
+    });
+    if (rows.length >= limit) break;
+  }
+  return rows;
+}
+
+cli({
+  site: "moegirl",
+  name: "search",
+  description:
+    "Search Moegirl ACG wiki articles for characters, works, songs, games, and studios",
+  domain: "zh.moegirl.org.cn",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 10 },
+  ],
+  columns: ["rank", "title", "description", "url"],
+  func: async (_page, kwargs) => {
+    const query = requireText(kwargs.query, "query");
+    const limit = requireLimit(kwargs.limit);
+    const url = new URL(`${ORIGIN}/api.php`);
+    url.searchParams.set("action", "opensearch");
+    url.searchParams.set("search", query);
+    url.searchParams.set("limit", String(limit));
+    url.searchParams.set("namespace", "0");
+    url.searchParams.set("format", "json");
+    const rows = mapMoegirlOpenSearch(await fetchJson(url.toString()), limit);
+    if (rows.length === 0)
+      throw new Error(`No Moegirl pages found for "${query}".`);
+    return rows;
+  },
+});
+
+cli({
+  site: "moegirl",
+  name: "page",
+  description: "Read a Moegirl article as plain text with metadata",
+  domain: "zh.moegirl.org.cn",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "title", type: "str", required: true, positional: true },
+    {
+      name: "paragraphs",
+      type: "int",
+      default: 0,
+      description: "Paragraph cap, 0 means full",
+    },
+  ],
+  columns: [
+    "title",
+    "description",
+    "categories",
+    "paragraphs",
+    "extract",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const title = requireText(kwargs.title, "title");
+    const paragraphCap = requireParagraphCap(kwargs.paragraphs);
+    return [
+      parseMoegirlPageHtml(
+        await fetchText(articleUrl(title)),
+        title,
+        paragraphCap,
+      ),
+    ];
+  },
+});
+
+cli({
+  site: "moegirl",
+  name: "links",
+  description:
+    "Extract internal Moegirl article links from a page, useful for disambiguation pages",
+  domain: "zh.moegirl.org.cn",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "title", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+    {
+      name: "contains",
+      type: "str",
+      description: "Only return links whose title contains this text",
+    },
+  ],
+  columns: ["rank", "title", "url"],
+  func: async (_page, kwargs) => {
+    const title = requireText(kwargs.title, "title");
+    const rows = parseMoegirlLinksHtml(
+      await fetchText(articleUrl(title)),
+      requireLimit(kwargs.limit),
+      str(kwargs.contains),
+    );
+    if (rows.length === 0)
+      throw new Error(`No Moegirl links found on "${title}".`);
+    return rows;
+  },
+});

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