@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/dockerhub/registry.ts

@@ -0,0 +1,223 @@
+/**
+ * @owner   src/adapters/dockerhub/registry.ts
+ * @does    Register agent-facing Docker Hub search and image metadata commands.
+ * @needs   Public Docker Hub API, TypeScript adapter loader, bounded argument parsing.
+ * @feeds   surface coverage ledger, container registry command surface, agent-readable image rows.
+ * @breaks  Docker Hub API envelope drift, weak image parsing, or silent empty results hide registry lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const HUB_BASE = "https://hub.docker.com/v2";
+
+interface DockerHubSearchItem {
+  repo_owner?: unknown;
+  repo_name?: unknown;
+  is_official?: unknown;
+  star_count?: unknown;
+  pull_count?: unknown;
+  short_description?: unknown;
+}
+
+interface DockerHubImageBody {
+  namespace?: unknown;
+  name?: unknown;
+  star_count?: unknown;
+  pull_count?: unknown;
+  description?: unknown;
+  last_updated?: unknown;
+  last_modified?: unknown;
+  date_registered?: unknown;
+  status_description?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function requireDockerHubString(value: unknown, name: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`${name} is required.`);
+  return text;
+}
+
+export function requireDockerHubLimit(
+  value: unknown,
+  fallback: number,
+): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 100) {
+    throw new Error(
+      `limit must be an integer in [1, 100]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+export function parseDockerHubImage(value: unknown): {
+  owner: string;
+  name: string;
+} {
+  const raw = requireDockerHubString(value, "image");
+  const parts = raw.split("/").filter(Boolean);
+  if (parts.length === 1) return { owner: "library", name: parts[0] };
+  if (parts.length === 2) return { owner: parts[0], name: parts[1] };
+  throw new Error(
+    "image must be a Docker Hub image name like nginx or bitnami/redis.",
+  );
+}
+
+function trimDate(value: unknown): string | null {
+  const text = stringField(value).trim();
+  if (!text) return null;
+  const noFraction = text.replace(/\.\d+/, "");
+  return noFraction.endsWith("Z") ? noFraction : `${noFraction}Z`;
+}
+
+async function fetchDockerHubJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: { Accept: "application/json" },
+  });
+  if (!response.ok) {
+    throw new Error(`Docker Hub request failed: HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+export function mapDockerHubSearchRows(
+  items: DockerHubSearchItem[],
+  limit: number,
+): Array<Record<string, unknown>> {
+  return items.slice(0, limit).map((item, index) => {
+    const owner = stringField(item.repo_owner).trim();
+    const name = stringField(item.repo_name).trim();
+    const official = Boolean(item.is_official);
+    const image = owner
+      ? `${owner}/${name}`
+      : official
+        ? `library/${name}`
+        : name;
+    return {
+      rank: index + 1,
+      image,
+      official,
+      stars: numberField(item.star_count),
+      pulls: numberField(item.pull_count),
+      description: stringField(item.short_description).trim(),
+      url: image ? `https://hub.docker.com/r/${image}` : "",
+    };
+  });
+}
+
+export function mapDockerHubImageRow(
+  body: DockerHubImageBody,
+  fallbackOwner: string,
+  fallbackName: string,
+): Record<string, unknown> {
+  const namespace = stringField(body.namespace).trim() || fallbackOwner;
+  const name = stringField(body.name).trim() || fallbackName;
+  if (!name) throw new Error("Docker Hub returned no image metadata.");
+  const official = namespace === "library" || namespace === "_";
+  const image = official ? `library/${name}` : `${namespace}/${name}`;
+  return {
+    image,
+    official,
+    stars: numberField(body.star_count),
+    pulls: numberField(body.pull_count),
+    description: stringField(body.description).trim(),
+    lastUpdated: trimDate(body.last_updated),
+    lastModified: trimDate(body.last_modified),
+    registered: trimDate(body.date_registered),
+    status: stringField(body.status_description).trim(),
+    url: `https://hub.docker.com/r/${image}`,
+  };
+}
+
+cli({
+  site: "dockerhub",
+  name: "search",
+  description: "Search Docker Hub repositories by keyword",
+  domain: "hub.docker.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Search keyword",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max repositories",
+    },
+  ],
+  columns: [
+    "rank",
+    "image",
+    "official",
+    "stars",
+    "pulls",
+    "description",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const query = requireDockerHubString(kwargs.query, "query");
+    const limit = requireDockerHubLimit(kwargs.limit, 25);
+    const url = `${HUB_BASE}/search/repositories/?query=${encodeURIComponent(query)}&page_size=${limit}`;
+    const body = (await fetchDockerHubJson(url)) as {
+      results?: DockerHubSearchItem[];
+    };
+    const rows = mapDockerHubSearchRows(
+      Array.isArray(body.results) ? body.results : [],
+      limit,
+    );
+    if (rows.length === 0) {
+      throw new Error(`No Docker Hub repositories matched "${query}".`);
+    }
+    return rows;
+  },
+});
+
+cli({
+  site: "dockerhub",
+  name: "image",
+  description: "Fetch a Docker Hub repository's public metadata",
+  domain: "hub.docker.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "image",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Image name, e.g. nginx or bitnami/redis",
+    },
+  ],
+  columns: [
+    "image",
+    "official",
+    "stars",
+    "pulls",
+    "description",
+    "lastUpdated",
+    "lastModified",
+    "registered",
+    "status",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const { owner, name } = parseDockerHubImage(kwargs.image);
+    const body = (await fetchDockerHubJson(
+      `${HUB_BASE}/repositories/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/`,
+    )) as DockerHubImageBody;
+    return [mapDockerHubImageRow(body, owner, name)];
+  },
+});

package/src/adapters/endoflife/product.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapEndoflifeRows,
+  normalizeEndoflifeDateOrFlag,
+  requireEndoflifeProduct,
+} from "./product.js";
+
+describe("endoflife agent-facing product command", () => {
+  it("validates product slugs", () => {
+    expect(requireEndoflifeProduct(" NodeJS ")).toBe("nodejs");
+    expect(requireEndoflifeProduct("ubuntu-24.04")).toBe("ubuntu-24.04");
+    expect(() => requireEndoflifeProduct("../node")).toThrow("valid slug");
+  });
+
+  it("normalizes date and boolean lifecycle fields", () => {
+    expect(normalizeEndoflifeDateOrFlag(true)).toBe("ongoing");
+    expect(normalizeEndoflifeDateOrFlag(false)).toBeNull();
+    expect(normalizeEndoflifeDateOrFlag(" 2027-01-01 ")).toBe("2027-01-01");
+  });
+
+  it("maps cycle rows with derived EOL status", () => {
+    expect(
+      mapEndoflifeRows(
+        "nodejs",
+        [
+          {
+            cycle: "22",
+            releaseDate: "2024-04-24",
+            latest: "22.1.0",
+            latestReleaseDate: "2024-05-01",
+            lts: true,
+            support: "2027-04-30",
+            eol: "2027-04-30",
+          },
+          { cycle: "10", eol: "2021-04-30" },
+        ],
+        "2026-05-12",
+      ),
+    ).toMatchObject([
+      {
+        product: "nodejs",
+        cycle: "22",
+        lts: "ongoing",
+        eolStatus: "active",
+        url: "https://endoflife.date/nodejs",
+      },
+      { cycle: "10", eolStatus: "eol" },
+    ]);
+  });
+});

package/src/adapters/endoflife/product.ts

@@ -0,0 +1,128 @@
+/**
+ * @owner   src/adapters/endoflife/product.ts
+ * @does    Register agent-facing endoflife.date product lifecycle command.
+ * @needs   endoflife.date public API, product slug validation, date/flag normalization.
+ * @feeds   surface coverage ledger, product support lifecycle rows, version planning data.
+ * @breaks  endoflife.date API drift, weak slug validation, or silent empty rows hide lifecycle data failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://endoflife.date/api";
+const PRODUCT_RE = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+
+export function requireEndoflifeProduct(value: unknown): string {
+  const product = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!product) throw new Error("endoflife product cannot be empty.");
+  if (!PRODUCT_RE.test(product)) {
+    throw new Error(
+      `endoflife product "${String(value)}" is not a valid slug.`,
+    );
+  }
+  return product;
+}
+
+export function normalizeEndoflifeDateOrFlag(value: unknown): string | null {
+  if (value === true) return "ongoing";
+  if (value === false || value == null) return null;
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  return text || null;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function mapEndoflifeRows(
+  product: string,
+  cycles: Array<Record<string, unknown>>,
+  today: string,
+): Array<Record<string, unknown>> {
+  return cycles.map((cycle) => {
+    const eol = normalizeEndoflifeDateOrFlag(cycle.eol);
+    const eolStatus =
+      eol === "ongoing"
+        ? "ongoing"
+        : typeof eol === "string" && eol >= today
+          ? "active"
+          : typeof eol === "string"
+            ? "eol"
+            : null;
+    return {
+      product,
+      cycle: stringField(cycle.cycle),
+      releaseDate: stringField(cycle.releaseDate),
+      latest: stringField(cycle.latest),
+      latestReleaseDate: stringField(cycle.latestReleaseDate),
+      lts: normalizeEndoflifeDateOrFlag(cycle.lts),
+      support: normalizeEndoflifeDateOrFlag(cycle.support),
+      eol,
+      extendedSupport: normalizeEndoflifeDateOrFlag(cycle.extendedSupport),
+      eolStatus,
+      url: `https://endoflife.date/${product}`,
+    };
+  });
+}
+
+async function fetchJson(url: URL | string, label: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-endoflife (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: "endoflife",
+  name: "product",
+  description: "Release cycles and support dates for an endoflife.date product",
+  domain: "endoflife.date",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "product",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "endoflife.date product slug",
+    },
+  ],
+  columns: [
+    "product",
+    "cycle",
+    "releaseDate",
+    "latest",
+    "latestReleaseDate",
+    "lts",
+    "support",
+    "eol",
+    "extendedSupport",
+    "eolStatus",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const product = requireEndoflifeProduct(kwargs.product);
+    const body = await fetchJson(
+      `${API_BASE}/${encodeURIComponent(product)}.json`,
+      "endoflife product",
+    );
+    const rows = mapEndoflifeRows(
+      product,
+      Array.isArray(body) ? (body as Array<Record<string, unknown>>) : [],
+      new Date().toISOString().slice(0, 10),
+    );
+    if (rows.length === 0) {
+      throw new Error(`endoflife product returned no cycles for "${product}".`);
+    }
+    return rows;
+  },
+});

package/src/adapters/facebook/marketplace-extra.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { requireFacebookMarketplaceLimit } from "./marketplace-extra.js";
+
+function pageMock(evaluateResults: unknown[]) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(async () => evaluateResults.shift()),
+  };
+}
+
+describe("facebook marketplace agent-facing commands", () => {
+  it("validates limits without silent clamps", () => {
+    expect(requireFacebookMarketplaceLimit(undefined)).toBe(20);
+    expect(requireFacebookMarketplaceLimit(2)).toBe(2);
+    expect(() => requireFacebookMarketplaceLimit(0)).toThrow(
+      "positive integer",
+    );
+    expect(() => requireFacebookMarketplaceLimit(101)).toThrow("<= 100");
+  });
+
+  it("lists Marketplace seller listings", async () => {
+    const command = resolveCommand("facebook", "marketplace-listings")?.command;
+    const page = pageMock([
+      {
+        authRequired: false,
+        rows: [
+          {
+            title: "Black electric standing desk",
+            price: "CA$80",
+            status: "Active",
+            listed: "Listed on 4/26",
+            clicks: "87",
+            actions: ["Mark as sold", "Share"],
+          },
+          {
+            title: "Large gray corduroy beanbag chair",
+            price: "CA$30",
+          },
+        ],
+      },
+    ]);
+    await expect(command!.func!(page, { limit: 1 })).resolves.toEqual([
+      {
+        index: 1,
+        title: "Black electric standing desk",
+        price: "CA$80",
+        status: "Active",
+        listed: "Listed on 4/26",
+        clicks: "87",
+        actions: "Mark as sold, Share",
+      },
+    ]);
+    expect(page.goto).toHaveBeenCalledWith(
+      "https://www.facebook.com/marketplace/you/selling/",
+    );
+    expect(page.wait).toHaveBeenCalledWith(4);
+  });
+
+  it("lists Marketplace inbox conversations", async () => {
+    const command = resolveCommand("facebook", "marketplace-inbox")?.command;
+    const page = pageMock([
+      {
+        authRequired: false,
+        rows: [
+          {
+            buyer: "Kulwant",
+            listing: "White 3-tier rolling utility cart",
+            snippet: "Can I pick up today?",
+            time: "3:43 PM",
+            unread: true,
+          },
+          {
+            buyer: "Gabriel",
+            listing: "Black electric standing desk",
+            snippet: "Yes, still available.",
+            time: "12:17 PM",
+            unread: false,
+          },
+        ],
+      },
+    ]);
+    await expect(command!.func!(page, { limit: 2 })).resolves.toEqual([
+      {
+        index: 1,
+        buyer: "Kulwant",
+        listing: "White 3-tier rolling utility cart",
+        snippet: "Can I pick up today?",
+        time: "3:43 PM",
+        unread: true,
+      },
+      {
+        index: 2,
+        buyer: "Gabriel",
+        listing: "Black electric standing desk",
+        snippet: "Yes, still available.",
+        time: "12:17 PM",
+        unread: false,
+      },
+    ]);
+    expect(page.goto).toHaveBeenCalledWith(
+      "https://www.facebook.com/marketplace/inbox/",
+    );
+    expect(page.wait).toHaveBeenCalledWith(4);
+  });
+
+  it("fails before navigation on invalid limits", async () => {
+    const command = resolveCommand("facebook", "marketplace-listings")?.command;
+    const page = pageMock([]);
+    await expect(command!.func!(page, { limit: 0 })).rejects.toThrow(
+      "positive integer",
+    );
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it("classifies auth and empty Marketplace pages", async () => {
+    const listings = resolveCommand(
+      "facebook",
+      "marketplace-listings",
+    )?.command;
+    const inbox = resolveCommand("facebook", "marketplace-inbox")?.command;
+    await expect(
+      listings!.func!(pageMock([{ authRequired: true, rows: [] }]), {
+        limit: 5,
+      }),
+    ).rejects.toThrow("requires an active signed-in Facebook session");
+    await expect(
+      inbox!.func!(pageMock([{ authRequired: false, rows: [] }]), { limit: 5 }),
+    ).rejects.toThrow("No Facebook Marketplace inbox conversations");
+  });
+});