@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/hackernews/read.ts

@@ -0,0 +1,265 @@
+/**
+ * @owner   src/adapters/hackernews/read.ts
+ * @does    Register agent-facing Hacker News story reader with threaded comments.
+ * @needs   Public Firebase item API, bounded tree traversal, HTML-to-text conversion.
+ * @feeds   surface coverage ledger, HN story reading workflow, comment thread inspection.
+ * @breaks  HN item shape drift, weak traversal bounds, or HTML entity loss degrades story reads.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const HN_ITEM_BASE = "https://hacker-news.firebaseio.com/v0/item";
+
+interface HnItem {
+  id?: unknown;
+  type?: unknown;
+  by?: unknown;
+  title?: unknown;
+  text?: unknown;
+  url?: unknown;
+  score?: unknown;
+  kids?: unknown;
+  deleted?: unknown;
+  dead?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+export function requireHnItemId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!/^\d+$/.test(id))
+    throw new Error(`Invalid HN item id: ${String(value)}.`);
+  return id;
+}
+
+export function requirePositiveInt(
+  value: unknown,
+  fallback: number,
+  label: string,
+): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return n;
+}
+
+export function requireMinInt(
+  value: unknown,
+  fallback: number,
+  min: number,
+  label: string,
+): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min) {
+    throw new Error(`${label} must be an integer >= ${min}.`);
+  }
+  return n;
+}
+
+export function hnHtmlToText(html: unknown): string {
+  return String(html ?? "")
+    .replace(/<p>/gi, "\n\n")
+    .replace(/<\/p>/gi, "")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<i>(.*?)<\/i>/gi, "$1")
+    .replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, "$2 ($1)")
+    .replace(/<pre><code>([\s\S]*?)<\/code><\/pre>/gi, "\n$1\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&#x27;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#x2F;/g, "/")
+    .trim();
+}
+
+function indentLines(text: string, depth: number): string {
+  if (depth === 0) return text;
+  const prefix = `${"  ".repeat(depth)}> `;
+  return text
+    .split("\n")
+    .map((line) => `${prefix}${line}`)
+    .join("\n");
+}
+
+function childIds(item: HnItem): number[] {
+  return Array.isArray(item.kids)
+    ? item.kids.filter((id): id is number => Number.isInteger(id))
+    : [];
+}
+
+function truncate(text: string, maxLength: number, suffix: string): string {
+  return text.length > maxLength
+    ? `${text.slice(0, maxLength)}${suffix}`
+    : text;
+}
+
+export async function buildHnReadRows(
+  story: HnItem | null,
+  fetchItem: (id: number) => Promise<HnItem | null>,
+  options: {
+    limit: number;
+    maxDepth: number;
+    maxReplies: number;
+    maxLength: number;
+  },
+): Promise<Array<Record<string, unknown>>> {
+  if (!story || story.deleted || story.dead) {
+    throw new Error("HN story not found, deleted, or dead.");
+  }
+  const rows: Array<Record<string, unknown>> = [];
+  const storyBody = truncate(
+    hnHtmlToText(story.text),
+    options.maxLength,
+    "\n... [truncated]",
+  );
+  const storyParts = [stringField(story.title)];
+  if (storyBody) storyParts.push(`\n${storyBody}`);
+  if (story.url) storyParts.push(`\n${stringField(story.url)}`);
+  rows.push({
+    type: "POST",
+    author: stringField(story.by) || "[deleted]",
+    score: numberField(story.score),
+    text: storyParts.join("").trim(),
+  });
+
+  async function walkComment(
+    item: HnItem | null,
+    depth: number,
+  ): Promise<void> {
+    if (!item || item.deleted || item.dead || item.type !== "comment") return;
+    rows.push({
+      type: depth === 0 ? "L0" : `L${depth}`,
+      author: stringField(item.by) || "[deleted]",
+      score: "",
+      text: indentLines(
+        truncate(hnHtmlToText(item.text), options.maxLength, "..."),
+        depth,
+      ),
+    });
+
+    const kids = childIds(item);
+    if (depth + 1 >= options.maxDepth) {
+      if (kids.length > 0) {
+        rows.push({
+          type: `L${depth + 1}`,
+          author: "",
+          score: "",
+          text: `${"  ".repeat(depth + 1)}[+${kids.length} more replies]`,
+        });
+      }
+      return;
+    }
+
+    const visible = kids.slice(0, options.maxReplies);
+    for (const reply of await Promise.all(visible.map((id) => fetchItem(id)))) {
+      await walkComment(reply, depth + 1);
+    }
+    const hidden = kids.length - visible.length;
+    if (hidden > 0) {
+      rows.push({
+        type: `L${depth + 1}`,
+        author: "",
+        score: "",
+        text: `${"  ".repeat(depth + 1)}[+${hidden} more replies]`,
+      });
+    }
+  }
+
+  const topKids = childIds(story);
+  const visibleTop = topKids.slice(0, options.limit);
+  for (const comment of await Promise.all(
+    visibleTop.map((id) => fetchItem(id)),
+  )) {
+    await walkComment(comment, 0);
+  }
+  const hiddenTop = topKids.length - visibleTop.length;
+  if (hiddenTop > 0) {
+    rows.push({
+      type: "",
+      author: "",
+      score: "",
+      text: `[+${hiddenTop} more top-level comments]`,
+    });
+  }
+  return rows;
+}
+
+async function fetchHnItem(id: number): Promise<HnItem | null> {
+  const response = await fetch(`${HN_ITEM_BASE}/${id}.json`, {
+    headers: {
+      "User-Agent":
+        "unicli-hackernews/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (!response.ok)
+    throw new Error(`HN API returned HTTP ${response.status} for item ${id}.`);
+  return (await response.json()) as HnItem | null;
+}
+
+cli({
+  site: "hackernews",
+  name: "read",
+  description: "Read a Hacker News story and comment tree",
+  domain: "news.ycombinator.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "HN item id",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max top-level comments",
+    },
+    { name: "depth", type: "int", default: 2, description: "Max reply depth" },
+    {
+      name: "replies",
+      type: "int",
+      default: 5,
+      description: "Max replies per comment",
+    },
+    {
+      name: "max-length",
+      type: "int",
+      default: 2000,
+      description: "Max chars per body",
+    },
+  ],
+  columns: ["type", "author", "score", "text"],
+  func: async (_page, kwargs) => {
+    const id = Number(requireHnItemId(kwargs.id));
+    return buildHnReadRows(await fetchHnItem(id), fetchHnItem, {
+      limit: requirePositiveInt(kwargs.limit, 25, "hackernews read limit"),
+      maxDepth: requirePositiveInt(kwargs.depth, 2, "hackernews read depth"),
+      maxReplies: requirePositiveInt(
+        kwargs.replies,
+        5,
+        "hackernews read replies",
+      ),
+      maxLength: requireMinInt(
+        kwargs["max-length"] ?? kwargs.maxLength,
+        2000,
+        100,
+        "hackernews read max-length",
+      ),
+    });
+  },
+});

package/src/adapters/hf/paper.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { hfEndpoint, mapHfPaperRow, requireHfPaperId } from "./paper.js";
+
+describe("hf agent-facing paper command", () => {
+  it("validates modern arXiv ids", () => {
+    expect(requireHfPaperId(" 1706.03762v3 ")).toBe("1706.03762v3");
+    expect(requireHfPaperId("2501.12345")).toBe("2501.12345");
+    expect(() => requireHfPaperId("cs/9901001")).toThrow("valid arXiv");
+    expect(() => requireHfPaperId("")).toThrow("cannot be empty");
+  });
+
+  it("normalizes endpoint values", () => {
+    expect(hfEndpoint("https://hf.example///")).toBe("https://hf.example");
+    expect(hfEndpoint("")).toBe("https://huggingface.co");
+  });
+
+  it("maps HF paper data to stable columns", () => {
+    expect(
+      mapHfPaperRow(
+        {
+          id: "1706.03762",
+          title: "Attention Is All You Need",
+          authors: [{ name: "Ashish Vaswani" }, { fullname: "Noam Shazeer" }],
+          publishedAt: "2017-06-12T00:00:00.000Z",
+          upvotes: 1234,
+          ai_keywords: ["transformer", "attention"],
+          summary: "Paper summary",
+          ai_summary: "AI summary",
+        },
+        "https://hf.example/",
+      ),
+    ).toEqual({
+      id: "1706.03762",
+      title: "Attention Is All You Need",
+      authors: "Ashish Vaswani, Noam Shazeer",
+      publishedAt: "2017-06-12",
+      upvotes: 1234,
+      aiKeywords: "transformer, attention",
+      summary: "Paper summary",
+      aiSummary: "AI summary",
+      url: "https://hf.example/papers/1706.03762",
+    });
+  });
+
+  it("rejects empty HF paper payloads", () => {
+    expect(() => mapHfPaperRow({})).toThrow("no paper data");
+  });
+});

package/src/adapters/hf/paper.ts

@@ -0,0 +1,138 @@
+/**
+ * @owner   src/adapters/hf/paper.ts
+ * @does    Register agent-facing Hugging Face paper detail command.
+ * @needs   Hugging Face public papers API, modern arXiv ids, paper metadata normalization.
+ * @feeds   surface coverage ledger, HF daily paper detail workflows, scholarly metadata readers.
+ * @breaks  HF papers API shape drift or invalid arXiv id handling can hide paper details.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const HF_DEFAULT_ENDPOINT = "https://huggingface.co";
+const ARXIV_ID_PATTERN = /^\d{4}\.\d{4,5}(?:v\d+)?$/;
+
+interface HfAuthor {
+  name?: unknown;
+  fullname?: unknown;
+}
+
+interface HfPaper {
+  id?: unknown;
+  title?: unknown;
+  authors?: unknown;
+  publishedAt?: unknown;
+  upvotes?: unknown;
+  ai_keywords?: unknown;
+  summary?: unknown;
+  ai_summary?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function numberOrNull(value: unknown): number | null {
+  if (value === undefined || value === null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function requireHfPaperId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!id) throw new Error("hf paper id cannot be empty.");
+  if (!ARXIV_ID_PATTERN.test(id)) {
+    throw new Error(`hf paper id "${String(value)}" is not a valid arXiv id.`);
+  }
+  return id;
+}
+
+export function hfEndpoint(value = process.env.HF_ENDPOINT): string {
+  return (value || HF_DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+
+function hfAuthorNames(value: unknown): string {
+  if (!Array.isArray(value)) return "";
+  return value
+    .map((author: HfAuthor | string) => {
+      if (typeof author === "string") return author;
+      return stringField(author.name || author.fullname);
+    })
+    .filter(Boolean)
+    .join(", ");
+}
+
+export function mapHfPaperRow(
+  paper: HfPaper,
+  endpoint = HF_DEFAULT_ENDPOINT,
+): Record<string, unknown> {
+  const id = stringField(paper.id);
+  if (!id) throw new Error("Hugging Face returned no paper data.");
+  return {
+    id,
+    title: stringField(paper.title),
+    authors: hfAuthorNames(paper.authors),
+    publishedAt: stringField(paper.publishedAt).slice(0, 10),
+    upvotes: numberOrNull(paper.upvotes),
+    aiKeywords: Array.isArray(paper.ai_keywords)
+      ? paper.ai_keywords.map(String).join(", ")
+      : "",
+    summary: stringField(paper.summary),
+    aiSummary: stringField(paper.ai_summary),
+    url: `${hfEndpoint(endpoint)}/papers/${id}`,
+  };
+}
+
+async function fetchHfPaper(id: string): Promise<HfPaper> {
+  const endpoint = hfEndpoint();
+  const response = await fetch(
+    `${endpoint}/api/papers/${encodeURIComponent(id)}`,
+    {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": "unicli-hf/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      },
+    },
+  );
+  if (response.status === 404) {
+    throw new Error(`Hugging Face has no paper page for "${id}".`);
+  }
+  if (response.status === 429) {
+    throw new Error("Hugging Face paper API returned HTTP 429.");
+  }
+  if (!response.ok)
+    throw new Error(`Hugging Face paper API returned HTTP ${response.status}.`);
+  return (await response.json()) as HfPaper;
+}
+
+cli({
+  site: "hf",
+  name: "paper",
+  description: "Hugging Face paper detail by arXiv id",
+  domain: "huggingface.co",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "arXiv id",
+    },
+  ],
+  columns: [
+    "id",
+    "title",
+    "authors",
+    "publishedAt",
+    "upvotes",
+    "aiKeywords",
+    "summary",
+    "aiSummary",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireHfPaperId(kwargs.id);
+    return [mapHfPaperRow(await fetchHfPaper(id), hfEndpoint())];
+  },
+});

package/src/adapters/homebrew/packages.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapCaskRow,
+  mapFormulaRow,
+  mapPopularRows,
+  requireHomebrewLimit,
+  requireHomebrewToken,
+  requirePopularType,
+  requirePopularWindow,
+} from "./packages.js";
+
+describe("homebrew agent-facing package commands", () => {
+  it("validates tokens, limits, and analytics selectors", () => {
+    expect(requireHomebrewToken(" gcc@13 ", "formula")).toBe("gcc@13");
+    expect(() => requireHomebrewToken("../gcc", "formula")).toThrow(
+      "not valid",
+    );
+    expect(requireHomebrewLimit(undefined, 30)).toBe(30);
+    expect(requireHomebrewLimit("500", 30)).toBe(500);
+    expect(() => requireHomebrewLimit("501", 30)).toThrow(
+      "limit must be an integer",
+    );
+    expect(requirePopularType("cask")).toBe("cask");
+    expect(() => requirePopularType("tap")).toThrow(
+      "type must be formula or cask",
+    );
+    expect(requirePopularWindow("365d")).toBe("365d");
+    expect(() => requirePopularWindow("7d")).toThrow("window must be");
+  });
+
+  it("maps formula metadata with dependency and source columns", () => {
+    expect(
+      mapFormulaRow(
+        {
+          name: "wget",
+          tap: "homebrew/core",
+          versions: { stable: "1.25.0" },
+          license: "GPL-3.0-or-later",
+          desc: "Internet file retriever",
+          homepage: "https://www.gnu.org/software/wget/",
+          dependencies: ["openssl@3", "libidn2"],
+          deprecated: false,
+          disabled: true,
+          urls: { stable: { url: "https://example.test/wget.tar.gz" } },
+        },
+        "wget",
+      ),
+    ).toEqual({
+      formula: "wget",
+      tap: "homebrew/core",
+      version: "1.25.0",
+      license: "GPL-3.0-or-later",
+      description: "Internet file retriever",
+      homepage: "https://www.gnu.org/software/wget/",
+      dependencies: "openssl@3, libidn2",
+      deprecated: false,
+      disabled: true,
+      source: "https://example.test/wget.tar.gz",
+      url: "https://formulae.brew.sh/formula/wget",
+    });
+  });
+
+  it("maps cask and analytics rows without sentinel output", () => {
+    expect(
+      mapCaskRow(
+        {
+          token: "firefox",
+          tap: "homebrew/cask",
+          name: ["Mozilla Firefox"],
+          version: "100",
+          desc: "Browser",
+          homepage: "https://firefox.com",
+          url: "https://example.test/firefox.dmg",
+        },
+        "firefox",
+      ),
+    ).toMatchObject({
+      cask: "firefox",
+      name: "Mozilla Firefox",
+      download: "https://example.test/firefox.dmg",
+    });
+
+    expect(
+      mapPopularRows(
+        {
+          items: [
+            { number: "2", formula: "node", count: "1,234", percent: "12.5" },
+          ],
+        },
+        "formula",
+        "30d",
+        10,
+      ),
+    ).toEqual([
+      {
+        rank: 2,
+        token: "node",
+        type: "formula",
+        installs: 1234,
+        percent: 12.5,
+        window: "30d",
+        url: "https://formulae.brew.sh/formula/node",
+      },
+    ]);
+    expect(() => mapPopularRows({ items: [] }, "cask", "90d", 1)).toThrow(
+      "returned no rows",
+    );
+  });
+});