@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/mdn/search.ts

@@ -0,0 +1,133 @@
+/**
+ * @owner   src/adapters/mdn/search.ts
+ * @does    Register agent-facing MDN Web Docs search command.
+ * @needs   MDN public search API, bounded limits, locale allowlist.
+ * @feeds   surface coverage ledger, web-platform documentation search rows.
+ * @breaks  MDN API drift, weak locale validation, or silent empty rows hide documentation lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://developer.mozilla.org";
+const LOCALES = new Set([
+  "de",
+  "en-US",
+  "es",
+  "fr",
+  "ja",
+  "ko",
+  "pt-BR",
+  "ru",
+  "zh-CN",
+  "zh-TW",
+]);
+
+function requireNonEmpty(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`mdn ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireMdnLimit(value: unknown): number {
+  const raw =
+    value === undefined || value === null || value === "" ? 10 : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+    throw new Error("mdn limit must be an integer in [1, 50].");
+  }
+  return limit;
+}
+
+export function requireMdnLocale(value: unknown): string {
+  const locale = String(value ?? "en-US").trim();
+  if (!LOCALES.has(locale)) {
+    throw new Error(`mdn locale "${String(value)}" is not supported.`);
+  }
+  return locale;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function mapMdnRows(
+  documents: Array<Record<string, unknown>>,
+  limit: number,
+  fallbackLocale: string,
+): Array<Record<string, unknown>> {
+  return documents.slice(0, limit).map((doc, index) => {
+    const mdnUrl = stringField(doc.mdn_url);
+    return {
+      rank: index + 1,
+      title: stringField(doc.title),
+      slug: stringField(doc.slug),
+      locale: stringField(doc.locale) || fallbackLocale,
+      summary: stringField(doc.summary).replace(/\s+/g, " "),
+      url: mdnUrl ? `${API_BASE}${mdnUrl}` : "",
+    };
+  });
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-mdn (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: "mdn",
+  name: "search",
+  description: "Search MDN Web Docs by keyword",
+  domain: "developer.mozilla.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Search keyword",
+    },
+    { name: "limit", type: "int", default: 10, description: "Max rows" },
+    {
+      name: "locale",
+      type: "str",
+      default: "en-US",
+      description: "MDN locale",
+    },
+  ],
+  columns: ["rank", "title", "slug", "locale", "summary", "url"],
+  func: async (_page, kwargs) => {
+    const query = requireNonEmpty(kwargs.query, "query");
+    const limit = requireMdnLimit(kwargs.limit);
+    const locale = requireMdnLocale(kwargs.locale);
+    const url = new URL(`${API_BASE}/api/v1/search`);
+    url.searchParams.set("q", query);
+    url.searchParams.set("locale", locale);
+    url.searchParams.set("size", String(limit));
+    const body = (await fetchJson(url, "mdn search")) as {
+      documents?: unknown;
+    };
+    const rows = mapMdnRows(
+      Array.isArray(body.documents)
+        ? (body.documents as Array<Record<string, unknown>>)
+        : [],
+      limit,
+      locale,
+    );
+    if (rows.length === 0) {
+      throw new Error(
+        `mdn search returned no rows for "${query}" (${locale}).`,
+      );
+    }
+    return rows;
+  },
+});

package/src/adapters/medium/tag.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeMediumHtml,
+  extractMediumCategories,
+  mediumRssDate,
+  parseMediumTagRss,
+  requireMediumLimit,
+  requireMediumTag,
+  stripMediumHtml,
+} from "./tag.js";
+
+describe("medium agent-facing tag command", () => {
+  it("validates tag slugs and limits", () => {
+    expect(requireMediumTag(" Machine-Learning ")).toBe("machine-learning");
+    expect(() => requireMediumTag("bad/tag")).toThrow("not valid");
+    expect(requireMediumLimit(undefined)).toBe(20);
+    expect(requireMediumLimit("25")).toBe(25);
+    expect(() => requireMediumLimit("26")).toThrow("[1, 25]");
+  });
+
+  it("decodes and strips Medium RSS text", () => {
+    expect(decodeMediumHtml("A&#39;s &lt;B&gt; &amp; C")).toBe("A's <B> & C");
+    expect(stripMediumHtml("<p>Hello&nbsp;<strong>world</strong></p>")).toBe(
+      "Hello world",
+    );
+    expect(mediumRssDate("Tue, 12 May 2026 01:02:03 GMT")).toBe("2026-05-12");
+    expect(mediumRssDate("not a date")).toBe("");
+  });
+
+  it("parses RSS items into stable columns", () => {
+    const xml = `
+      <rss><channel>
+        <item>
+          <title><![CDATA[AI &amp; Agents]]></title>
+          <dc:creator><![CDATA[Jane Doe]]></dc:creator>
+          <description><![CDATA[<p>Readable <a href="https://x.test">summary</a></p>]]></description>
+          <category><![CDATA[AI]]></category>
+          <category>Programming</category>
+          <pubDate>Tue, 12 May 2026 01:02:03 GMT</pubDate>
+          <link>https://medium.com/p/example</link>
+        </item>
+      </channel></rss>
+    `;
+
+    expect(extractMediumCategories(xml)).toEqual(["AI", "Programming"]);
+    expect(parseMediumTagRss(xml, 20)).toEqual([
+      {
+        rank: 1,
+        title: "AI & Agents",
+        author: "Jane Doe",
+        description: "Readable summary",
+        categories: "AI, Programming",
+        published: "2026-05-12",
+        url: "https://medium.com/p/example",
+      },
+    ]);
+  });
+
+  it("rejects empty RSS feeds", () => {
+    expect(() => parseMediumTagRss("<rss><channel /></rss>", 20)).toThrow(
+      "no items",
+    );
+  });
+});

package/src/adapters/medium/tag.ts

@@ -0,0 +1,164 @@
+/**
+ * @owner   src/adapters/medium/tag.ts
+ * @does    Register agent-facing Medium tag RSS reader.
+ * @needs   Medium public tag RSS feed, strict tag slugs, bounded item parsing.
+ * @feeds   surface coverage ledger, Medium topical article discovery, RSS reading workflows.
+ * @breaks  Medium RSS shape drift or weak entity stripping degrades tag article rows.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const MEDIUM_TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/i;
+const MEDIUM_TAG_LIMIT = 25;
+const HTML_ENTITIES: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&apos;": "'",
+  "&#39;": "'",
+  "&nbsp;": " ",
+};
+
+export function requireMediumTag(value: unknown): string {
+  const tag = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!tag) throw new Error("medium tag is required.");
+  if (!MEDIUM_TAG_PATTERN.test(tag)) {
+    throw new Error(`medium tag "${String(value)}" is not valid.`);
+  }
+  return tag;
+}
+
+export function requireMediumLimit(value: unknown, fallback = 20): number {
+  const raw =
+    value === undefined || value === null || value === "" ? fallback : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MEDIUM_TAG_LIMIT) {
+    throw new Error(
+      `medium limit must be an integer in [1, ${MEDIUM_TAG_LIMIT}].`,
+    );
+  }
+  return limit;
+}
+
+export function decodeMediumHtml(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex: string) => {
+      const code = Number.parseInt(hex, 16);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : "";
+    })
+    .replace(/&#(\d+);/g, (_, dec: string) => {
+      const code = Number.parseInt(dec, 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : "";
+    })
+    .replace(/&(amp|lt|gt|quot|apos|#39|nbsp);/g, (match) => {
+      return HTML_ENTITIES[match] ?? match;
+    });
+}
+
+function extractXmlTag(block: string, tag: string): string {
+  const cdata = block.match(
+    new RegExp(
+      `<${tag}[^>]*>\\s*<!\\[CDATA\\[([\\s\\S]*?)\\]\\]>\\s*<\\/${tag}>`,
+    ),
+  );
+  if (cdata) return cdata[1] ?? "";
+  const plain = block.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`));
+  return plain?.[1] ?? "";
+}
+
+export function stripMediumHtml(value: unknown): string {
+  return decodeMediumHtml(String(value ?? "").replace(/<[^>]+>/g, " "))
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function mediumRssDate(value: unknown): string {
+  const raw = String(value ?? "").trim();
+  if (!raw) return "";
+  const date = new Date(raw);
+  return Number.isNaN(date.getTime()) ? "" : date.toISOString().slice(0, 10);
+}
+
+export function extractMediumCategories(block: string): string[] {
+  const categories: string[] = [];
+  const re =
+    /<category(?:[^>]*)>(?:<!\[CDATA\[([\s\S]*?)\]\]>|([\s\S]*?))<\/category>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(block)) !== null) {
+    const category = decodeMediumHtml((match[1] ?? match[2] ?? "").trim());
+    if (category) categories.push(category);
+  }
+  return categories;
+}
+
+export function parseMediumTagRss(
+  xml: string,
+  limit: number,
+): Array<Record<string, unknown>> {
+  const items: string[] = [];
+  const re = /<item[^>]*>([\s\S]*?)<\/item>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml)) !== null) {
+    if (match[1]) items.push(match[1]);
+  }
+  if (items.length === 0) throw new Error("Medium tag RSS feed has no items.");
+  return items.slice(0, limit).map((block, index) => ({
+    rank: index + 1,
+    title: decodeMediumHtml(extractXmlTag(block, "title")).trim(),
+    author: decodeMediumHtml(extractXmlTag(block, "dc:creator")).trim(),
+    description: stripMediumHtml(extractXmlTag(block, "description")),
+    categories: extractMediumCategories(block).join(", "),
+    published: mediumRssDate(decodeMediumHtml(extractXmlTag(block, "pubDate"))),
+    url: decodeMediumHtml(extractXmlTag(block, "link")).trim(),
+  }));
+}
+
+async function fetchMediumTagRss(tag: string): Promise<string> {
+  const response = await fetch(`https://medium.com/feed/tag/${tag}`, {
+    headers: {
+      Accept: "application/rss+xml, application/xml",
+      "User-Agent": "unicli-medium/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  });
+  if (response.status === 404)
+    throw new Error(`Medium tag "${tag}" does not exist.`);
+  if (!response.ok)
+    throw new Error(`Medium tag returned HTTP ${response.status}.`);
+  return response.text();
+}
+
+cli({
+  site: "medium",
+  name: "tag",
+  description: "Latest Medium articles tagged with a keyword from RSS",
+  domain: "medium.com",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    {
+      name: "tag",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Medium tag slug",
+    },
+    { name: "limit", type: "int", default: 20, description: "Max articles" },
+  ],
+  columns: [
+    "rank",
+    "title",
+    "author",
+    "description",
+    "categories",
+    "published",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const tag = requireMediumTag(kwargs.tag);
+    const limit = requireMediumLimit(kwargs.limit);
+    return parseMediumTagRss(await fetchMediumTagRss(tag), limit);
+  },
+});

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