@zenalexa/unicli 0.218.1 → 0.220.0

package/dist/adapters/hackernews/read.js

@@ -0,0 +1,201 @@
+/**
+ * @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";
+function stringField(value) {
+    return typeof value === "string" ? value : "";
+}
+function numberField(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+export function requireHnItemId(value) {
+    const id = String(value ?? "").trim();
+    if (!/^\d+$/.test(id))
+        throw new Error(`Invalid HN item id: ${String(value)}.`);
+    return id;
+}
+export function requirePositiveInt(value, fallback, label) {
+    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, fallback, min, label) {
+    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) {
+    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, depth) {
+    if (depth === 0)
+        return text;
+    const prefix = `${"  ".repeat(depth)}> `;
+    return text
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+function childIds(item) {
+    return Array.isArray(item.kids)
+        ? item.kids.filter((id) => Number.isInteger(id))
+        : [];
+}
+function truncate(text, maxLength, suffix) {
+    return text.length > maxLength
+        ? `${text.slice(0, maxLength)}${suffix}`
+        : text;
+}
+export async function buildHnReadRows(story, fetchItem, options) {
+    if (!story || story.deleted || story.dead) {
+        throw new Error("HN story not found, deleted, or dead.");
+    }
+    const rows = [];
+    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, depth) {
+        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) {
+    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());
+}
+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"),
+        });
+    },
+});
+//# sourceMappingURL=read.js.map

package/dist/adapters/hackernews/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/adapters/hackernews/read.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,YAAY,GAAG,4CAA4C,CAAC;AAelE,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3D,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,QAAgB,EAChB,KAAa;IAEb,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC3E,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8BAA8B,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAc,EACd,QAAgB,EAChB,GAAW,EACX,KAAa;IAEb,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC3E,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,0BAA0B,GAAG,GAAG,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;SACtB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC;SAC7B,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC;SAChC,OAAO,CAAC,yCAAyC,EAAE,SAAS,CAAC;SAC7D,OAAO,CAAC,wCAAwC,EAAE,QAAQ,CAAC;SAC3D,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,KAAa;IAC9C,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IACzC,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC;SACjC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAC7B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAAgB,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,SAAiB,EAAE,MAAc;IAC/D,OAAO,IAAI,CAAC,MAAM,GAAG,SAAS;QAC5B,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,EAAE;QACxC,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,SAAiD,EACjD,OAKC;IAED,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,GAAmC,EAAE,CAAC;IAChD,MAAM,SAAS,GAAG,QAAQ,CACxB,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,EACxB,OAAO,CAAC,SAAS,EACjB,mBAAmB,CACpB,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,IAAI,SAAS;QAAE,UAAU,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,GAAG;QAAE,UAAU,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9D,IAAI,CAAC,IAAI,CAAC;QACR,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,WAAW;QAC5C,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC;QAC/B,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE;KACjC,CAAC,CAAC;IAEH,KAAK,UAAU,WAAW,CACxB,IAAmB,EACnB,KAAa;QAEb,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO;QAC1E,IAAI,CAAC,IAAI,CAAC;YACR,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE;YACtC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,WAAW;YAC3C,KAAK,EAAE,EAAE;YACT,IAAI,EAAE,WAAW,CACf,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,EAC3D,KAAK,CACN;SACF,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC;oBACR,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,EAAE;oBACrB,MAAM,EAAE,EAAE;oBACV,KAAK,EAAE,EAAE;oBACT,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,gBAAgB;iBAChE,CAAC,CAAC;YACL,CAAC;YACD,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QAClD,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC5C,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,CAAC;gBACR,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,EAAE;gBACrB,MAAM,EAAE,EAAE;gBACV,KAAK,EAAE,EAAE;gBACT,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,MAAM,gBAAgB;aAC3D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACnD,KAAK,MAAM,OAAO,IAAI,MAAM,OAAO,CAAC,GAAG,CACrC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CACtC,EAAE,CAAC;QACF,MAAM,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;IACrD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC;YACR,IAAI,EAAE,EAAE;YACR,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,EAAE;YACT,IAAI,EAAE,KAAK,SAAS,2BAA2B;SAChD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,EAAU;IACnC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,IAAI,EAAE,OAAO,EAAE;QACzD,OAAO,EAAE;YACP,YAAY,EACV,+DAA+D;YACjE,MAAM,EAAE,kBAAkB;SAC3B;KACF,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE;QACd,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,CAAC;IAC7E,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAkB,CAAC;AAClD,CAAC;AAED,GAAG,CAAC;IACF,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,2CAA2C;IACxD,MAAM,EAAE,sBAAsB;IAC9B,QAAQ,EAAE,QAAQ,CAAC,MAAM;IACzB,IAAI,EAAE;QACJ;YACE,IAAI,EAAE,IAAI;YACV,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,IAAI;YAChB,WAAW,EAAE,YAAY;SAC1B;QACD;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,wBAAwB;SACtC;QACD,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,iBAAiB,EAAE;QAC1E;YACE,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,CAAC;YACV,WAAW,EAAE,yBAAyB;SACvC;QACD;YACE,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,oBAAoB;SAClC;KACF;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC;IAC5C,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAC5B,MAAM,EAAE,GAAG,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9C,OAAO,eAAe,CAAC,MAAM,WAAW,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE;YACzD,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,uBAAuB,CAAC;YACpE,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,uBAAuB,CAAC;YACtE,UAAU,EAAE,kBAAkB,CAC5B,MAAM,CAAC,OAAO,EACd,CAAC,EACD,yBAAyB,CAC1B;YACD,SAAS,EAAE,aAAa,CACtB,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,SAAS,EACxC,IAAI,EACJ,GAAG,EACH,4BAA4B,CAC7B;SACF,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}

package/dist/adapters/hf/paper.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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.
+ */
+interface HfPaper {
+    id?: unknown;
+    title?: unknown;
+    authors?: unknown;
+    publishedAt?: unknown;
+    upvotes?: unknown;
+    ai_keywords?: unknown;
+    summary?: unknown;
+    ai_summary?: unknown;
+}
+export declare function requireHfPaperId(value: unknown): string;
+export declare function hfEndpoint(value?: string | undefined): string;
+export declare function mapHfPaperRow(paper: HfPaper, endpoint?: string): Record<string, unknown>;
+export {};
+//# sourceMappingURL=paper.d.ts.map

package/dist/adapters/hf/paper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper.d.ts","sourceRoot":"","sources":["../../../src/adapters/hf/paper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,UAAU,OAAO;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAYD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOvD;AAED,wBAAgB,UAAU,CAAC,KAAK,qBAA0B,GAAG,MAAM,CAElE;AAaD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,QAAQ,SAAsB,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBzB"}

package/dist/adapters/hf/paper.js

@@ -0,0 +1,112 @@
+/**
+ * @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+)?$/;
+function stringField(value) {
+    return value === undefined || value === null ? "" : String(value);
+}
+function numberOrNull(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+export function requireHfPaperId(value) {
+    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) {
+    return (value || HF_DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+function hfAuthorNames(value) {
+    if (!Array.isArray(value))
+        return "";
+    return value
+        .map((author) => {
+        if (typeof author === "string")
+            return author;
+        return stringField(author.name || author.fullname);
+    })
+        .filter(Boolean)
+        .join(", ");
+}
+export function mapHfPaperRow(paper, endpoint = HF_DEFAULT_ENDPOINT) {
+    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) {
+    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());
+}
+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())];
+    },
+});
+//# sourceMappingURL=paper.js.map

package/dist/adapters/hf/paper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper.js","sourceRoot":"","sources":["../../../src/adapters/hf/paper.ts"],"names":[],"mappings":"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"}

package/dist/adapters/homebrew/packages.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @owner   src/adapters/homebrew/packages.ts
+ * @does    Register agent-facing Homebrew formula, cask, and popularity commands.
+ * @needs   formulae.brew.sh public JSON APIs and bounded argument parsing.
+ * @feeds   surface coverage ledger, package registry command surface, Homebrew package inspection.
+ * @breaks  Homebrew API drift, weak token validation, or silent analytics empties hide package lookup failures.
+ */
+declare const POPULAR_TYPES: readonly ["formula", "cask"];
+declare const POPULAR_WINDOWS: readonly ["30d", "90d", "365d"];
+type PopularType = (typeof POPULAR_TYPES)[number];
+type PopularWindow = (typeof POPULAR_WINDOWS)[number];
+interface HomebrewFormulaBody {
+    name?: unknown;
+    tap?: unknown;
+    versions?: {
+        stable?: unknown;
+    };
+    license?: unknown;
+    desc?: unknown;
+    homepage?: unknown;
+    dependencies?: unknown;
+    deprecated?: unknown;
+    disabled?: unknown;
+    urls?: {
+        stable?: {
+            url?: unknown;
+        };
+    };
+}
+interface HomebrewCaskBody {
+    token?: unknown;
+    tap?: unknown;
+    name?: unknown;
+    version?: unknown;
+    desc?: unknown;
+    homepage?: unknown;
+    deprecated?: unknown;
+    disabled?: unknown;
+    url?: unknown;
+}
+interface HomebrewAnalyticsBody {
+    items?: Array<Record<string, unknown>>;
+}
+export declare function requireHomebrewToken(value: unknown, label: string): string;
+export declare function requireHomebrewLimit(value: unknown, fallback: number): number;
+export declare function requirePopularType(value: unknown): PopularType;
+export declare function requirePopularWindow(value: unknown): PopularWindow;
+export declare function mapFormulaRow(body: HomebrewFormulaBody, requested: string): Record<string, unknown>;
+export declare function mapCaskRow(body: HomebrewCaskBody, requested: string): Record<string, unknown>;
+export declare function mapPopularRows(body: HomebrewAnalyticsBody, type: PopularType, window: PopularWindow, limit: number): Array<Record<string, unknown>>;
+export {};
+//# sourceMappingURL=packages.d.ts.map

package/dist/adapters/homebrew/packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../../src/adapters/homebrew/packages.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,QAAA,MAAM,aAAa,8BAA+B,CAAC;AACnD,QAAA,MAAM,eAAe,iCAAkC,CAAC;AAExD,KAAK,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAClD,KAAK,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,UAAU,mBAAmB;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE;YAAE,GAAG,CAAC,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC;CACvC;AAED,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,UAAU,qBAAqB;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC;AAiBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO1E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS7E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAQ9D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAMlE;AAeD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAsBhC"}

package/dist/adapters/homebrew/packages.js

@@ -0,0 +1,240 @@
+/**
+ * @owner   src/adapters/homebrew/packages.ts
+ * @does    Register agent-facing Homebrew formula, cask, and popularity commands.
+ * @needs   formulae.brew.sh public JSON APIs and bounded argument parsing.
+ * @feeds   surface coverage ledger, package registry command surface, Homebrew package inspection.
+ * @breaks  Homebrew API drift, weak token validation, or silent analytics empties hide package lookup failures.
+ */
+import { cli, Strategy } from "../../registry.js";
+const BREW_BASE = "https://formulae.brew.sh/api";
+const POPULAR_TYPES = ["formula", "cask"];
+const POPULAR_WINDOWS = ["30d", "90d", "365d"];
+function stringField(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function boolField(value) {
+    return value === true;
+}
+function numberField(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value !== "string")
+        return null;
+    const n = Number(value.replace(/,/g, ""));
+    return Number.isFinite(n) ? n : null;
+}
+export function requireHomebrewToken(value, label) {
+    const token = String(value ?? "").trim();
+    if (!token)
+        throw new Error(`homebrew ${label} is required.`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._@+-]*$/.test(token)) {
+        throw new Error(`homebrew ${label} "${String(value)}" is not valid.`);
+    }
+    return token;
+}
+export function requireHomebrewLimit(value, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 500) {
+        throw new Error(`limit must be an integer in [1, 500]. Got: ${String(value)}`);
+    }
+    return n;
+}
+export function requirePopularType(value) {
+    const type = String(value ?? "formula")
+        .trim()
+        .toLowerCase();
+    if (type !== "formula" && type !== "cask") {
+        throw new Error("type must be formula or cask.");
+    }
+    return type;
+}
+export function requirePopularWindow(value) {
+    const window = String(value ?? "30d").trim();
+    if (window !== "30d" && window !== "90d" && window !== "365d") {
+        throw new Error("window must be 30d, 90d, or 365d.");
+    }
+    return window;
+}
+async function fetchHomebrewJson(url, label) {
+    const response = await fetch(url, {
+        headers: {
+            "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+            Accept: "application/json",
+        },
+    });
+    if (response.status === 404)
+        throw new Error(`${label} returned no result.`);
+    if (!response.ok)
+        throw new Error(`${label} returned HTTP ${response.status}.`);
+    return response.json();
+}
+export function mapFormulaRow(body, requested) {
+    const formula = stringField(body.name) || requested;
+    const dependencies = Array.isArray(body.dependencies)
+        ? body.dependencies.map(stringField).filter(Boolean).join(", ")
+        : "";
+    if (!formula)
+        throw new Error(`Homebrew returned no formula metadata.`);
+    return {
+        formula,
+        tap: stringField(body.tap),
+        version: stringField(body.versions?.stable),
+        license: stringField(body.license),
+        description: stringField(body.desc),
+        homepage: stringField(body.homepage),
+        dependencies,
+        deprecated: boolField(body.deprecated),
+        disabled: boolField(body.disabled),
+        source: stringField(body.urls?.stable?.url),
+        url: `https://formulae.brew.sh/formula/${encodeURIComponent(formula)}`,
+    };
+}
+export function mapCaskRow(body, requested) {
+    const cask = stringField(body.token) || requested;
+    const name = Array.isArray(body.name)
+        ? body.name.map(stringField).filter(Boolean).join(", ")
+        : stringField(body.name);
+    if (!cask)
+        throw new Error(`Homebrew returned no cask metadata.`);
+    return {
+        cask,
+        tap: stringField(body.tap),
+        name,
+        version: stringField(body.version),
+        description: stringField(body.desc),
+        homepage: stringField(body.homepage),
+        deprecated: boolField(body.deprecated),
+        disabled: boolField(body.disabled),
+        download: stringField(body.url),
+        url: `https://formulae.brew.sh/cask/${encodeURIComponent(cask)}`,
+    };
+}
+export function mapPopularRows(body, type, window, limit) {
+    const items = Array.isArray(body.items) ? body.items : [];
+    if (items.length === 0) {
+        throw new Error(`Homebrew analytics returned no rows for ${type}/${window}.`);
+    }
+    return items.slice(0, limit).map((row, index) => {
+        const token = stringField(type === "cask" ? row.cask : row.formula);
+        const detailPath = type === "cask" ? "cask" : "formula";
+        return {
+            rank: numberField(row.number) ?? index + 1,
+            token,
+            type,
+            installs: numberField(row.count),
+            percent: numberField(row.percent),
+            window,
+            url: token
+                ? `https://formulae.brew.sh/${detailPath}/${encodeURIComponent(token)}`
+                : "",
+        };
+    });
+}
+cli({
+    site: "homebrew",
+    name: "formula",
+    description: "Fetch Homebrew formula metadata",
+    domain: "formulae.brew.sh",
+    strategy: Strategy.PUBLIC,
+    args: [
+        {
+            name: "name",
+            type: "str",
+            required: true,
+            positional: true,
+            description: "Formula name",
+        },
+    ],
+    columns: [
+        "formula",
+        "tap",
+        "version",
+        "license",
+        "description",
+        "homepage",
+        "dependencies",
+        "deprecated",
+        "disabled",
+        "source",
+        "url",
+    ],
+    func: async (_page, kwargs) => {
+        const name = requireHomebrewToken(kwargs.name, "formula");
+        const body = (await fetchHomebrewJson(`${BREW_BASE}/formula/${encodeURIComponent(name)}.json`, `homebrew formula ${name}`));
+        return [mapFormulaRow(body, name)];
+    },
+});
+cli({
+    site: "homebrew",
+    name: "cask",
+    description: "Fetch Homebrew cask metadata",
+    domain: "formulae.brew.sh",
+    strategy: Strategy.PUBLIC,
+    args: [
+        {
+            name: "token",
+            type: "str",
+            required: true,
+            positional: true,
+            description: "Cask token",
+        },
+    ],
+    columns: [
+        "cask",
+        "tap",
+        "name",
+        "version",
+        "description",
+        "homepage",
+        "deprecated",
+        "disabled",
+        "download",
+        "url",
+    ],
+    func: async (_page, kwargs) => {
+        const token = requireHomebrewToken(kwargs.token, "cask");
+        const body = (await fetchHomebrewJson(`${BREW_BASE}/cask/${encodeURIComponent(token)}.json`, `homebrew cask ${token}`));
+        return [mapCaskRow(body, token)];
+    },
+});
+cli({
+    site: "homebrew",
+    name: "popular",
+    description: "List most-installed Homebrew formulae or casks",
+    domain: "formulae.brew.sh",
+    strategy: Strategy.PUBLIC,
+    args: [
+        {
+            name: "type",
+            type: "str",
+            default: "formula",
+            choices: ["formula", "cask"],
+            description: "Package type",
+        },
+        {
+            name: "window",
+            type: "str",
+            default: "30d",
+            choices: ["30d", "90d", "365d"],
+            description: "Homebrew analytics window",
+        },
+        {
+            name: "limit",
+            type: "int",
+            default: 30,
+            description: "Max rows",
+        },
+    ],
+    columns: ["rank", "token", "type", "installs", "percent", "window", "url"],
+    func: async (_page, kwargs) => {
+        const type = requirePopularType(kwargs.type);
+        const window = requirePopularWindow(kwargs.window);
+        const limit = requireHomebrewLimit(kwargs.limit, 30);
+        const path = type === "cask" ? "cask-install" : "install";
+        const body = (await fetchHomebrewJson(`${BREW_BASE}/analytics/${path}/${window}.json`, `homebrew popular ${type}/${window}`));
+        return mapPopularRows(body, type, window, limit);
+    },
+});
+//# sourceMappingURL=packages.js.map