@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/maven/artifact.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapMavenArtifactRows,
+  parseMavenCoordinate,
+  requireMavenLimit,
+} from "./artifact.js";
+
+describe("maven agent-facing artifact command", () => {
+  it("parses coordinates and validates limits", () => {
+    expect(parseMavenCoordinate(" org.example:lib ")).toEqual({
+      groupId: "org.example",
+      artifactId: "lib",
+      version: "",
+    });
+    expect(parseMavenCoordinate("org.example:lib:1.0.0")).toEqual({
+      groupId: "org.example",
+      artifactId: "lib",
+      version: "1.0.0",
+    });
+    expect(() => parseMavenCoordinate("org.example")).toThrow(
+      "coordinate must be",
+    );
+    expect(requireMavenLimit(undefined, 20)).toBe(20);
+    expect(requireMavenLimit("200", 20)).toBe(200);
+    expect(() => requireMavenLimit("201", 20)).toThrow(
+      "limit must be an integer",
+    );
+  });
+
+  it("maps gav rows newest-first shape with published timestamp", () => {
+    expect(
+      mapMavenArtifactRows(
+        {
+          response: {
+            docs: [
+              {
+                g: "org.example",
+                a: "lib",
+                v: "1.2.3",
+                p: "jar",
+                timestamp: 1770000000000,
+                tags: ["testing", "example"],
+              },
+            ],
+          },
+        },
+        { groupId: "org.example", artifactId: "lib", version: "" },
+      ),
+    ).toEqual([
+      {
+        groupId: "org.example",
+        artifactId: "lib",
+        version: "1.2.3",
+        packaging: "jar",
+        publishedAt: "2026-02-02T02:40:00.000Z",
+        tags: "testing, example",
+        url: "https://central.sonatype.com/artifact/org.example/lib/1.2.3",
+      },
+    ]);
+    expect(() =>
+      mapMavenArtifactRows(
+        { response: { docs: [] } },
+        { groupId: "g", artifactId: "a", version: "" },
+      ),
+    ).toThrow("no published versions");
+  });
+});

package/src/adapters/maven/artifact.ts

@@ -0,0 +1,155 @@
+/**
+ * @owner   src/adapters/maven/artifact.ts
+ * @does    Register agent-facing Maven Central artifact version history command.
+ * @needs   search.maven.org Solr gav core and coordinate validation.
+ * @feeds   surface coverage ledger, JVM dependency inspection, registry command surface.
+ * @breaks  Maven coordinate parsing or Solr envelope drift hides dependency versions.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const MAVEN_BASE = "https://search.maven.org/solrsearch/select";
+
+interface MavenDoc {
+  g?: unknown;
+  a?: unknown;
+  v?: unknown;
+  p?: unknown;
+  timestamp?: unknown;
+  tags?: unknown;
+}
+
+interface MavenBody {
+  response?: { docs?: MavenDoc[] };
+}
+
+export interface MavenCoordinate {
+  groupId: string;
+  artifactId: string;
+  version: string;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function epochMsToIso(value: unknown): string {
+  return typeof value === "number" && Number.isFinite(value)
+    ? new Date(value).toISOString()
+    : "";
+}
+
+export function requireMavenLimit(value: unknown, fallback: number): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 200) {
+    throw new Error(
+      `limit must be an integer in [1, 200]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+export function parseMavenCoordinate(value: unknown): MavenCoordinate {
+  const coordinate = String(value ?? "").trim();
+  const parts = coordinate.split(":").map((part) => part.trim());
+  if (parts.length !== 2 && parts.length !== 3) {
+    throw new Error(
+      'coordinate must be "groupId:artifactId" or "groupId:artifactId:version".',
+    );
+  }
+  const [groupId, artifactId, version = ""] = parts;
+  if (!groupId || !artifactId) {
+    throw new Error("coordinate groupId and artifactId are required.");
+  }
+  return { groupId, artifactId, version };
+}
+
+export function mapMavenArtifactRows(
+  body: MavenBody,
+  coordinate: MavenCoordinate,
+): Array<Record<string, unknown>> {
+  const docs = Array.isArray(body.response?.docs) ? body.response.docs : [];
+  if (docs.length === 0) {
+    const label = coordinate.version
+      ? `${coordinate.groupId}:${coordinate.artifactId}:${coordinate.version}`
+      : `${coordinate.groupId}:${coordinate.artifactId}`;
+    throw new Error(`Maven Central has no published versions for ${label}.`);
+  }
+  return docs.map((doc) => {
+    const version = stringField(doc.v);
+    return {
+      groupId: stringField(doc.g) || coordinate.groupId,
+      artifactId: stringField(doc.a) || coordinate.artifactId,
+      version,
+      packaging: stringField(doc.p),
+      publishedAt: epochMsToIso(doc.timestamp),
+      tags: Array.isArray(doc.tags)
+        ? doc.tags.map(stringField).filter(Boolean).join(", ")
+        : "",
+      url: version
+        ? `https://central.sonatype.com/artifact/${coordinate.groupId}/${coordinate.artifactId}/${version}`
+        : `https://central.sonatype.com/artifact/${coordinate.groupId}/${coordinate.artifactId}`,
+    };
+  });
+}
+
+async function fetchMavenJson(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.ok)
+    throw new Error(`maven artifact returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "maven",
+  name: "artifact",
+  description: "Fetch Maven Central artifact version history",
+  domain: "search.maven.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "coordinate",
+      type: "str",
+      required: true,
+      positional: true,
+      description: 'Maven coordinate "groupId:artifactId[:version]"',
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Max versions",
+    },
+  ],
+  columns: [
+    "groupId",
+    "artifactId",
+    "version",
+    "packaging",
+    "publishedAt",
+    "tags",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const coordinate = parseMavenCoordinate(kwargs.coordinate);
+    const limit = requireMavenLimit(kwargs.limit, 20);
+    const filters = [`g:${coordinate.groupId}`, `a:${coordinate.artifactId}`];
+    if (coordinate.version) filters.push(`v:${coordinate.version}`);
+    const params = new URLSearchParams({
+      q: filters.join(" AND "),
+      core: "gav",
+      rows: String(coordinate.version ? 1 : limit),
+      wt: "json",
+    });
+    const body = (await fetchMavenJson(
+      `${MAVEN_BASE}?${params.toString()}`,
+    )) as MavenBody;
+    return mapMavenArtifactRows(body, coordinate);
+  },
+});

package/src/adapters/mdn/search.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { mapMdnRows, requireMdnLimit, requireMdnLocale } from "./search.js";
+
+describe("mdn agent-facing search command", () => {
+  it("validates limit and locale", () => {
+    expect(requireMdnLimit(undefined)).toBe(10);
+    expect(requireMdnLimit("50")).toBe(50);
+    expect(() => requireMdnLimit("0")).toThrow("mdn limit must");
+    expect(requireMdnLocale("zh-CN")).toBe("zh-CN");
+    expect(() => requireMdnLocale("xx")).toThrow("not supported");
+  });
+
+  it("maps MDN search rows", () => {
+    expect(
+      mapMdnRows(
+        [
+          {
+            title: "Fetch API",
+            slug: "Web/API/Fetch_API",
+            locale: "",
+            summary: "  Promise-based\nHTTP requests. ",
+            mdn_url: "/en-US/docs/Web/API/Fetch_API",
+          },
+        ],
+        10,
+        "en-US",
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        title: "Fetch API",
+        slug: "Web/API/Fetch_API",
+        locale: "en-US",
+        summary: "Promise-based HTTP requests.",
+        url: "https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API",
+      },
+    ]);
+  });
+});

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