@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/rfc/rfc.ts

@@ -0,0 +1,133 @@
+/**
+ * @owner   src/adapters/rfc/rfc.ts
+ * @does    Register agent-facing IETF RFC metadata command.
+ * @needs   IETF datatracker public API, strict RFC number validation, date normalization.
+ * @feeds   surface coverage ledger, RFC metadata rows, standards cross-reference URLs.
+ * @breaks  Datatracker API drift, weak number parsing, or silent empty rows hide RFC metadata failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://datatracker.ietf.org";
+
+export function requireRfcNumber(value: unknown): number {
+  const text = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^rfc/, "");
+  if (!text) throw new Error("rfc number cannot be empty.");
+  if (!/^\d+$/.test(text))
+    throw new Error(`rfc number "${String(value)}" is not valid.`);
+  const number = Number(text);
+  if (!Number.isInteger(number) || number < 1 || number > 999_999) {
+    throw new Error("rfc number must be an integer in [1, 999999].");
+  }
+  return number;
+}
+
+export function trimRfcDate(value: unknown): string | null {
+  const text = String(value ?? "").trim();
+  return /^\d{4}-\d{2}-\d{2}/.test(text) ? text.slice(0, 10) : null;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function numberField(value: unknown): number | null {
+  const n =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim()
+        ? Number(value)
+        : NaN;
+  return Number.isFinite(n) ? n : null;
+}
+
+function objectField(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function mapRfcRow(
+  number: number,
+  doc: Record<string, unknown>,
+): Record<string, unknown> {
+  const authors = Array.isArray(doc.authors)
+    ? doc.authors
+        .map((author) => stringField(objectField(author).name))
+        .filter(Boolean)
+        .join(", ")
+    : "";
+  const group = objectField(doc.group);
+  const name = `rfc${number}`;
+  return {
+    rfc: number,
+    title: stringField(doc.title),
+    state: stringField(doc.state),
+    stdLevel: stringField(doc.std_level),
+    group: stringField(group.name),
+    groupType: stringField(group.type),
+    pages: numberField(doc.pages),
+    published: trimRfcDate(doc.time),
+    authors,
+    abstract: stringField(doc.abstract),
+    rfcEditorUrl: `https://www.rfc-editor.org/rfc/rfc${number}`,
+    url: `${API_BASE}/doc/${name}/`,
+  };
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-rfc (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: "rfc",
+  name: "rfc",
+  description: "Fetch IETF RFC metadata by RFC number",
+  domain: "datatracker.ietf.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "number",
+      type: "int",
+      required: true,
+      positional: true,
+      description: "RFC number",
+    },
+  ],
+  columns: [
+    "rfc",
+    "title",
+    "state",
+    "stdLevel",
+    "group",
+    "groupType",
+    "pages",
+    "published",
+    "authors",
+    "abstract",
+    "rfcEditorUrl",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const number = requireRfcNumber(kwargs.number);
+    const doc = objectField(
+      await fetchJson(`${API_BASE}/doc/rfc${number}/doc.json`, "rfc rfc"),
+    );
+    if (!doc.name)
+      throw new Error(`rfc rfc returned no metadata for RFC ${number}.`);
+    return [mapRfcRow(number, doc)];
+  },
+});

package/src/adapters/rubygems/gem.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { mapRubyGemRow, requireGemName } from "./gem.js";
+
+describe("rubygems agent-facing gem command", () => {
+  it("validates gem tokens", () => {
+    expect(requireGemName(" rails ")).toBe("rails");
+    expect(() => requireGemName("../rails")).toThrow("gem name must be");
+  });
+
+  it("maps gem metadata with source and bug tracker fallbacks", () => {
+    expect(
+      mapRubyGemRow(
+        {
+          name: "rails",
+          version: "8.0.0",
+          version_created_at: "2026-05-01T00:00:00.000Z",
+          downloads: 1000,
+          version_downloads: 100,
+          licenses: ["MIT"],
+          authors: "DHH",
+          homepage_uri: "https://rubyonrails.org",
+          metadata: {
+            source_code_uri: "https://github.com/rails/rails",
+            bug_tracker_uri: "https://github.com/rails/rails/issues",
+          },
+          info: "Rails is a framework",
+          project_uri: "https://rubygems.org/gems/rails",
+        },
+        "rails",
+      ),
+    ).toMatchObject({
+      gem: "rails",
+      version: "8.0.0",
+      releasedAt: "2026-05-01",
+      downloads: 1000,
+      versionDownloads: 100,
+      license: "MIT",
+      authors: "DHH",
+      source: "https://github.com/rails/rails",
+      bugs: "https://github.com/rails/rails/issues",
+    });
+  });
+});

package/src/adapters/rubygems/gem.ts

@@ -0,0 +1,126 @@
+/**
+ * @owner   src/adapters/rubygems/gem.ts
+ * @does    Register agent-facing RubyGems single-gem metadata command.
+ * @needs   rubygems.org public gem JSON API.
+ * @feeds   surface coverage ledger, Ruby dependency inspection, registry command surface.
+ * @breaks  RubyGems envelope drift or weak gem-name validation hides gem metadata.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const GEMS_BASE = "https://rubygems.org/api/v1";
+
+interface RubyGemBody {
+  name?: unknown;
+  version?: unknown;
+  version_created_at?: unknown;
+  downloads?: unknown;
+  version_downloads?: unknown;
+  licenses?: unknown;
+  authors?: unknown;
+  homepage_uri?: unknown;
+  source_code_uri?: unknown;
+  bug_tracker_uri?: unknown;
+  metadata?: Record<string, unknown>;
+  info?: unknown;
+  project_uri?: unknown;
+}
+
+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 requireGemName(value: unknown): string {
+  const name = String(value ?? "").trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+    throw new Error("gem name must be a non-empty RubyGems token.");
+  }
+  return name;
+}
+
+export function mapRubyGemRow(
+  body: RubyGemBody,
+  requested: string,
+): Record<string, unknown> {
+  const name = stringField(body.name) || requested;
+  if (!name) throw new Error(`RubyGems returned no metadata for ${requested}.`);
+  const licenses = Array.isArray(body.licenses)
+    ? body.licenses.map(stringField).filter(Boolean).join(", ")
+    : "";
+  const metadata = body.metadata ?? {};
+  return {
+    gem: name,
+    version: stringField(body.version),
+    releasedAt: stringField(body.version_created_at).slice(0, 10),
+    downloads: numberField(body.downloads),
+    versionDownloads: numberField(body.version_downloads),
+    license: licenses,
+    authors: stringField(body.authors),
+    homepage: stringField(body.homepage_uri),
+    source:
+      stringField(body.source_code_uri) ||
+      stringField(metadata.source_code_uri),
+    bugs:
+      stringField(body.bug_tracker_uri) ||
+      stringField(metadata.bug_tracker_uri),
+    info: stringField(body.info),
+    url: stringField(body.project_uri) || `https://rubygems.org/gems/${name}`,
+  };
+}
+
+async function fetchGemJson(name: string): Promise<unknown> {
+  const response = await fetch(
+    `${GEMS_BASE}/gems/${encodeURIComponent(name)}.json`,
+    {
+      headers: {
+        "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+        Accept: "application/json",
+      },
+    },
+  );
+  if (response.status === 404)
+    throw new Error(`rubygems gem ${name} returned no result.`);
+  if (!response.ok)
+    throw new Error(`rubygems gem ${name} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "rubygems",
+  name: "gem",
+  description: "Fetch RubyGems gem metadata",
+  domain: "rubygems.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "name",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Gem name",
+    },
+  ],
+  columns: [
+    "gem",
+    "version",
+    "releasedAt",
+    "downloads",
+    "versionDownloads",
+    "license",
+    "authors",
+    "homepage",
+    "source",
+    "bugs",
+    "info",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const name = requireGemName(kwargs.name);
+    const body = (await fetchGemJson(name)) as RubyGemBody;
+    return [mapRubyGemRow(body, name)];
+  },
+});

package/src/adapters/stackoverflow/questions.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildStackReadRows,
+  decodeStackHtmlEntities,
+  mapStackQuestionRows,
+  mapStackUserRows,
+  requireStackLimit,
+  requireStackMinInt,
+  requireStackQuestionId,
+  requireStackString,
+  sortStackAnswers,
+  stackHtmlToText,
+} from "./questions.js";
+
+describe("stackoverflow agent-facing commands", () => {
+  it("validates ids, strings, limits, and converts Stack Exchange HTML", () => {
+    expect(requireStackQuestionId(" 79935770 ")).toBe("79935770");
+    expect(() => requireStackQuestionId("abc")).toThrow("numeric question id");
+    expect(requireStackString(" rust ", "tag")).toBe("rust");
+    expect(() => requireStackString("", "tag")).toThrow("cannot be empty");
+    expect(requireStackLimit(undefined, 20, 100, "limit")).toBe(20);
+    expect(() => requireStackLimit("101", 20, 100, "limit")).toThrow(
+      "[1, 100]",
+    );
+    expect(requireStackMinInt(undefined, 4000, 100, "max-length")).toBe(4000);
+    expect(() => requireStackMinInt("99", 4000, 100, "max-length")).toThrow(
+      ">= 100",
+    );
+    expect(decodeStackHtmlEntities("Rust's <Trait> & API")).toBe(
+      "Rust's <Trait> & API",
+    );
+    expect(
+      stackHtmlToText(
+        '<p>Hello &amp; <code>world</code></p><ul><li><a href="https://x.test">link</a></li></ul>',
+      ),
+    ).toBe("Hello & `world`\n- link (https://x.test)");
+  });
+
+  it("maps question and user list rows with surface column names", () => {
+    expect(
+      mapStackQuestionRows([
+        {
+          question_id: 1,
+          title: "Use &lt;T&gt;",
+          score: 5,
+          answer_count: 2,
+          view_count: 99,
+          is_answered: true,
+          tags: ["typescript", "generics"],
+          owner: { display_name: "Jon&#39;s Bot" },
+          creation_date: 1_700_000_000,
+          last_activity_date: 1_700_100_000,
+        },
+      ]),
+    ).toEqual([
+      {
+        rank: 1,
+        id: 1,
+        title: "Use <T>",
+        score: 5,
+        answers: 2,
+        views: 99,
+        isAnswered: true,
+        tags: "typescript, generics",
+        author: "Jon's Bot",
+        createdAt: "2023-11-14",
+        lastActivityAt: "2023-11-16",
+        url: "https://stackoverflow.com/questions/1",
+      },
+    ]);
+
+    expect(
+      mapStackUserRows([
+        {
+          user_id: 22656,
+          display_name: "Jon Skeet",
+          reputation: 1_500_000,
+          badge_counts: { gold: 900, silver: 9000, bronze: 90000 },
+          location: "Reading &amp; London",
+          creation_date: 1_200_000_000,
+          last_access_date: 1_700_000_000,
+        },
+      ]),
+    ).toEqual([
+      {
+        userId: 22656,
+        displayName: "Jon Skeet",
+        reputation: 1_500_000,
+        goldBadges: 900,
+        silverBadges: 9000,
+        bronzeBadges: 90000,
+        location: "Reading & London",
+        createdAt: "2008-01-10",
+        lastAccessAt: "2023-11-14",
+        url: "https://stackoverflow.com/users/22656",
+      },
+    ]);
+  });
+
+  it("sorts accepted answers first and builds bounded read rows", async () => {
+    expect(
+      sortStackAnswers({ accepted_answer_id: 3 }, [
+        { answer_id: 2, score: 50 },
+        { answer_id: 3, score: 1 },
+        { answer_id: 4, score: 40 },
+      ]).map((answer) => answer.answer_id),
+    ).toEqual([3, 2, 4]);
+
+    const rows = await buildStackReadRows(
+      {
+        title: "Why?",
+        body: "<p>Question body</p>",
+        score: 10,
+        accepted_answer_id: 3,
+        owner: { display_name: "asker" },
+        link: "https://stackoverflow.com/q/1",
+      },
+      [{ body: "<p>Needs code</p>", score: 1, owner: { display_name: "c1" } }],
+      [
+        {
+          answer_id: 2,
+          body: "<p>High score</p>",
+          score: 20,
+          owner: { display_name: "a2" },
+        },
+        {
+          answer_id: 3,
+          is_accepted: true,
+          body: "<p>Accepted</p>",
+          score: 2,
+          owner: { display_name: "a3" },
+        },
+      ],
+      async () => ({
+        items: [
+          {
+            post_id: 3,
+            body: "<p>Good point</p>",
+            score: 0,
+            owner: { display_name: "c3" },
+          },
+        ],
+      }),
+      {
+        answersLimit: 2,
+        commentsLimit: 2,
+        maxLength: 100,
+        label: "stackoverflow/1",
+      },
+    );
+
+    expect(rows).toEqual([
+      {
+        type: "POST",
+        author: "asker",
+        score: 10,
+        accepted: "",
+        text: "Why?\n\nQuestion body\n\nhttps://stackoverflow.com/q/1",
+      },
+      {
+        type: "Q-COMMENT",
+        author: "c1",
+        score: 1,
+        accepted: "",
+        text: "  > Needs code",
+      },
+      {
+        type: "ANSWER",
+        author: "a3",
+        score: 2,
+        accepted: "true",
+        text: "Accepted",
+      },
+      {
+        type: "A-COMMENT",
+        author: "c3",
+        score: 0,
+        accepted: "",
+        text: "  > Good point",
+      },
+      {
+        type: "ANSWER",
+        author: "a2",
+        score: 20,
+        accepted: "",
+        text: "High score",
+      },
+    ]);
+  });
+
+  it("refuses partial answer-comment pages", async () => {
+    await expect(
+      buildStackReadRows(
+        { title: "Q", accepted_answer_id: 2 },
+        [],
+        [{ answer_id: 2 }],
+        async () => ({ items: [], has_more: true }),
+        {
+          answersLimit: 1,
+          commentsLimit: 2,
+          maxLength: 100,
+          label: "stackoverflow/2",
+        },
+      ),
+    ).rejects.toThrow("exceed one API page");
+  });
+});