@jackwener/opencli 1.7.11 → 1.7.13

package/clis/hackernews/read.js

@@ -0,0 +1,188 @@
+/**
+ * Hacker News story reader with threaded comment tree.
+ *
+ * Mirrors `reddit read` semantics — fetches a story plus a tree of top-level
+ * comments and inline replies via the public Firebase API:
+ *   https://hacker-news.firebaseio.com/v0/item/<id>.json
+ *
+ * Output rows:
+ *   - first row is the story itself (`type=POST`)
+ *   - each subsequent row is a comment, indented by depth (`L0`, `L1`, …)
+ *   - `[+N more replies]` summary rows whenever depth/limit cuts in
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const HN_ITEM_BASE = 'https://hacker-news.firebaseio.com/v0/item';
+
+async function fetchItem(id) {
+    const res = await fetch(`${HN_ITEM_BASE}/${id}.json`);
+    if (!res.ok) {
+        throw new CommandExecutionError(`HN API HTTP ${res.status} for item ${id}`, 'Check the item ID');
+    }
+    return res.json();
+}
+
+function requirePositiveInt(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new ArgumentError(`${label} must be a positive integer`);
+    }
+    return value;
+}
+
+function requireMinInt(value, min, label) {
+    if (!Number.isInteger(value) || value < min) {
+        throw new ArgumentError(`${label} must be an integer >= ${min}`);
+    }
+    return value;
+}
+
+/** HN stores comment text as a small HTML subset — convert to plain text. */
+function htmlToText(html) {
+    if (!html) return '';
+    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 indent = '  '.repeat(depth);
+    const prefix = `${indent}> `;
+    return text.split('\n').map((line) => prefix + line).join('\n');
+}
+
+function moreRepliesIndent(depth) {
+    return '  '.repeat(depth + 1);
+}
+
+cli({
+    site: 'hackernews',
+    name: 'read',
+    access: 'read',
+    description: 'Read a Hacker News story and its comment tree',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', required: true, positional: true, help: 'HN item ID (e.g. 39847301)' },
+        { name: 'limit', type: 'int', default: 25, help: 'Max top-level comments' },
+        { name: 'depth', type: 'int', default: 2, help: 'Max reply depth (1=no replies, 2=one level of replies, etc.)' },
+        { name: 'replies', type: 'int', default: 5, help: 'Max replies shown per comment at each level' },
+        { name: 'max-length', type: 'int', default: 2000, help: 'Max characters per comment body (min 100)' },
+    ],
+    columns: ['type', 'author', 'score', 'text'],
+    func: async (args) => {
+        const id = String(args.id || '').trim();
+        if (!/^\d+$/.test(id)) {
+            throw new ArgumentError(`Invalid HN item id: ${args.id}`, 'Pass a numeric id like 39847301');
+        }
+        const limit = requirePositiveInt(args.limit ?? 25, 'hackernews read --limit');
+        const maxDepth = requirePositiveInt(args.depth ?? 2, 'hackernews read --depth');
+        const maxReplies = requirePositiveInt(args.replies ?? 5, 'hackernews read --replies');
+        const maxLength = requireMinInt(args['max-length'] ?? 2000, 100, 'hackernews read --max-length');
+
+        const story = await fetchItem(id);
+        if (!story || story.deleted || story.dead) {
+            throw new EmptyResultError(`hackernews/${id}`, 'Story not found, deleted, or dead');
+        }
+
+        const results = [];
+
+        // Story header row. text combines title + selftext (Ask/Show HN body) + external URL.
+        const storyBodyRaw = htmlToText(story.text || '');
+        const storyBody = storyBodyRaw.length > maxLength
+            ? storyBodyRaw.slice(0, maxLength) + '\n... [truncated]'
+            : storyBodyRaw;
+        const storyParts = [story.title || ''];
+        if (storyBody) storyParts.push('\n' + storyBody);
+        if (story.url) storyParts.push('\n' + story.url);
+        results.push({
+            type: 'POST',
+            author: story.by || '[deleted]',
+            score: story.score ?? 0,
+            text: storyParts.join('').trim(),
+        });
+
+        // Walk top-level comments using `kids` ids; fetch the first `limit` ids in parallel.
+        const topKids = Array.isArray(story.kids) ? story.kids : [];
+        const topToFetch = topKids.slice(0, limit);
+        const fetched = await Promise.all(topToFetch.map((kidId) => fetchItem(kidId).catch(() => null)));
+
+        async function walkComment(node, depth) {
+            if (!node || node.deleted || node.dead || node.type !== 'comment') return;
+            const bodyText = htmlToText(node.text || '');
+            const truncated = bodyText.length > maxLength
+                ? bodyText.slice(0, maxLength) + '...'
+                : bodyText;
+
+            results.push({
+                type: depth === 0 ? 'L0' : `L${depth}`,
+                author: node.by || '[deleted]',
+                score: '',
+                text: indentLines(truncated, depth),
+            });
+
+            const childIds = Array.isArray(node.kids) ? node.kids : [];
+
+            // At depth cutoff: don't recurse, but show a "+N more replies" stub if any.
+            if (depth + 1 >= maxDepth) {
+                if (childIds.length > 0) {
+                    results.push({
+                        type: `L${depth + 1}`,
+                        author: '',
+                        score: '',
+                        text: `${moreRepliesIndent(depth)}[+${childIds.length} more replies]`,
+                    });
+                }
+                return;
+            }
+
+            const toProcess = childIds.slice(0, maxReplies);
+            const replies = await Promise.all(toProcess.map((cid) => fetchItem(cid).catch(() => null)));
+            for (const reply of replies) {
+                await walkComment(reply, depth + 1);
+            }
+
+            // "+N more replies" for whatever we skipped at this level
+            const hidden = childIds.length - toProcess.length;
+            if (hidden > 0) {
+                results.push({
+                    type: `L${depth + 1}`,
+                    author: '',
+                    score: '',
+                    text: `${moreRepliesIndent(depth)}[+${hidden} more replies]`,
+                });
+            }
+        }
+
+        for (const comment of fetched) {
+            await walkComment(comment, 0);
+        }
+
+        const hiddenTopLevel = Math.max(0, topKids.length - topToFetch.length);
+        if (hiddenTopLevel > 0) {
+            results.push({
+                type: '',
+                author: '',
+                score: '',
+                text: `[+${hiddenTopLevel} more top-level comments]`,
+            });
+        }
+
+        return results;
+    },
+});

package/clis/hackernews/search.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'search',
+    access: 'read',
     description: 'Search Hacker News stories',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -16,7 +17,7 @@ cli({
             choices: ['relevance', 'date'],
         },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments', 'url'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
     pipeline: [
         { fetch: {
                 url: `https://hn.algolia.com/api/v1/\${{ args.sort === 'date' ? 'search_by_date' : 'search' }}`,
@@ -25,6 +26,7 @@ cli({
         { select: 'hits' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.objectID }}',
                 title: '${{ item.title }}',
                 score: '${{ item.points }}',
                 author: '${{ item.author }}',

package/clis/hackernews/show.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'show',
+    access: 'read',
     description: 'Hacker News Show HN posts',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -9,7 +10,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
     pipeline: [
         { fetch: { url: 'https://hacker-news.firebaseio.com/v0/showstories.json' } },
         { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
@@ -18,6 +19,7 @@ cli({
         { filter: 'item.title && !item.deleted && !item.dead' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.by }}',

package/clis/hackernews/top.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'top',
+    access: 'read',
     description: 'Hacker News top stories',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -9,7 +10,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
     pipeline: [
         { fetch: { url: 'https://hacker-news.firebaseio.com/v0/topstories.json' } },
         { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
@@ -18,6 +19,7 @@ cli({
         { filter: 'item.title && !item.deleted && !item.dead' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.by }}',

package/clis/hackernews/user.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'user',
+    access: 'read',
     description: 'Hacker News user profile',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,

package/clis/hf/datasets.js

@@ -0,0 +1,88 @@
+// hf datasets — list top Hugging Face datasets.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+const SORT_OPTIONS = ['downloads', 'likes', 'trending', 'created_at', 'last_modified'];
+const SORT_ALIAS = { lastmodified: 'last_modified', createdat: 'created_at' };
+
+cli({
+    site: 'hf',
+    name: 'datasets',
+    access: 'read',
+    description: 'Top Hugging Face datasets (downloads / likes / trending / freshness).',
+    domain: 'huggingface.co',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'sort', type: 'string', default: 'downloads', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
+        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter.' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max datasets (max 100; one API page).' },
+    ],
+    columns: ['rank', 'id', 'author', 'downloads', 'likes', 'tags', 'lastModified', 'url'],
+    func: async (args) => {
+        const sortRaw = String(args.sort ?? 'downloads').toLowerCase();
+        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
+        if (!SORT_OPTIONS.includes(sort)) {
+            throw new ArgumentError(`hf datasets sort must be one of ${SORT_OPTIONS.join(', ')}`);
+        }
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('hf datasets limit must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('hf datasets limit must be <= 100');
+        }
+
+        const url = new URL('https://huggingface.co/api/datasets');
+        url.searchParams.set('sort', sort);
+        url.searchParams.set('direction', '-1');
+        url.searchParams.set('limit', String(limit));
+        url.searchParams.set('full', 'true');
+        if (args.search) url.searchParams.set('search', String(args.search));
+
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
+                },
+            });
+        } catch (error) {
+            throw new CommandExecutionError(`hf datasets request failed: ${error?.message || error}`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`hf datasets failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`hf datasets returned malformed JSON: ${error?.message || error}`);
+        }
+        const list = Array.isArray(data) ? data : [];
+        if (list.length === 0) {
+            throw new EmptyResultError('hf datasets', 'No matching datasets on huggingface.co.');
+        }
+        return list.slice(0, limit).map((d, i) => {
+            const id = d.id || '';
+            const slashIdx = id.indexOf('/');
+            const author = slashIdx > 0 ? id.slice(0, slashIdx) : '';
+            const tags = Array.isArray(d.tags) ? d.tags.filter(t => !t.startsWith('license:')).slice(0, 10).join(', ') : '';
+            return {
+                rank: i + 1,
+                id,
+                author,
+                downloads: d.downloads ?? 0,
+                likes: d.likes ?? 0,
+                tags,
+                lastModified: d.lastModified ? String(d.lastModified).slice(0, 10) : '',
+                url: id ? `https://huggingface.co/datasets/${id}` : '',
+            };
+        });
+    },
+});

package/clis/hf/hf.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './top.js';
+import './paper.js';
+
+describe('hf adapter registry contracts', () => {
+    it('declares hf top columns so paper ids round-trip into hf paper', () => {
+        const top = getRegistry().get('hf/top');
+        const paper = getRegistry().get('hf/paper');
+
+        expect(top).toBeDefined();
+        expect(paper).toBeDefined();
+        expect(top.columns).toEqual(['rank', 'id', 'title', 'upvotes', 'authors']);
+        expect(paper.columns).toContain('id');
+    });
+});

package/clis/hf/models.js

@@ -0,0 +1,91 @@
+// hf models — list top Hugging Face models (by downloads / likes / trending).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+const SORT_OPTIONS = ['downloads', 'likes', 'trending', 'created_at', 'last_modified'];
+const SORT_ALIAS = { lastmodified: 'last_modified', createdat: 'created_at' };
+
+cli({
+    site: 'hf',
+    name: 'models',
+    access: 'read',
+    description: 'Top Hugging Face models (downloads / likes / trending / freshness).',
+    domain: 'huggingface.co',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'sort', type: 'string', default: 'downloads', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
+        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter (e.g. "llama", "mistralai/")' },
+        { name: 'pipeline', type: 'string', required: false, help: 'Filter by pipeline tag (e.g. text-generation, image-classification)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max models (max 100; one API page).' },
+    ],
+    columns: ['rank', 'id', 'author', 'pipelineTag', 'downloads', 'likes', 'tags', 'lastModified', 'url'],
+    func: async (args) => {
+        const sortRaw = String(args.sort ?? 'downloads').toLowerCase();
+        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
+        if (!SORT_OPTIONS.includes(sort)) {
+            throw new ArgumentError(`hf models sort must be one of ${SORT_OPTIONS.join(', ')}`);
+        }
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('hf models limit must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('hf models limit must be <= 100');
+        }
+
+        const url = new URL('https://huggingface.co/api/models');
+        url.searchParams.set('sort', sort);
+        url.searchParams.set('direction', '-1');
+        url.searchParams.set('limit', String(limit));
+        url.searchParams.set('full', 'true');
+        if (args.search) url.searchParams.set('search', String(args.search));
+        if (args.pipeline) url.searchParams.set('pipeline_tag', String(args.pipeline));
+
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
+                },
+            });
+        } catch (error) {
+            throw new CommandExecutionError(`hf models request failed: ${error?.message || error}`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`hf models failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`hf models returned malformed JSON: ${error?.message || error}`);
+        }
+        const list = Array.isArray(data) ? data : [];
+        if (list.length === 0) {
+            throw new EmptyResultError('hf models', 'No matching models on huggingface.co.');
+        }
+        return list.slice(0, limit).map((m, i) => {
+            const id = m.id || m.modelId || '';
+            const slashIdx = id.indexOf('/');
+            const author = slashIdx > 0 ? id.slice(0, slashIdx) : '';
+            const tags = Array.isArray(m.tags) ? m.tags.filter(t => !t.startsWith('license:')).slice(0, 10).join(', ') : '';
+            return {
+                rank: i + 1,
+                id,
+                author,
+                pipelineTag: m.pipeline_tag || m.pipelineTag || '',
+                downloads: m.downloads ?? 0,
+                likes: m.likes ?? 0,
+                tags,
+                lastModified: m.lastModified ? String(m.lastModified).slice(0, 10) : '',
+                url: id ? `https://huggingface.co/${id}` : '',
+            };
+        });
+    },
+});

package/clis/hf/paper.js

@@ -0,0 +1,79 @@
+// hf paper — fetch a single Hugging Face paper page (mirrors arXiv id),
+// returning the full title / summary / upvote count / authors and the
+// AI-generated keyword list HF curates.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const ARXIV_ID_PATTERN = /^\d{4}\.\d{4,5}(?:v\d+)?$/;
+
+cli({
+    site: 'hf',
+    name: 'paper',
+    access: 'read',
+    description: 'Hugging Face paper detail by arXiv id (full title / summary / authors / AI keywords)',
+    domain: 'huggingface.co',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'arXiv id (e.g. "1706.03762") — same value HF uses to mirror the paper' },
+    ],
+    columns: ['id', 'title', 'authors', 'publishedAt', 'upvotes', 'aiKeywords', 'summary', 'aiSummary', 'url'],
+    func: async (args) => {
+        const raw = String(args.id ?? '').trim();
+        if (!raw) {
+            throw new ArgumentError('hf paper id cannot be empty', 'Example: opencli hf paper 1706.03762');
+        }
+        if (!ARXIV_ID_PATTERN.test(raw)) {
+            throw new ArgumentError(
+                `hf paper id "${args.id}" is not a valid arXiv id`,
+                'Expected the modern arXiv form `YYMM.NNNNN` (optionally with a version suffix like `v3`).',
+            );
+        }
+        const endpoint = process.env.HF_ENDPOINT?.replace(/\/+$/, '') || 'https://huggingface.co';
+        const url = `${endpoint}/api/papers/${encodeURIComponent(raw)}`;
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { accept: 'application/json' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`hf paper request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 404) {
+            throw new EmptyResultError('hf paper', `Hugging Face has no paper page for "${raw}".`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'hf paper returned HTTP 429 (rate limited)',
+                'Hugging Face throttles unauthenticated traffic; wait a few seconds and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`hf paper returned HTTP ${resp.status}`);
+        }
+        let body;
+        try {
+            body = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`hf paper returned malformed JSON: ${err?.message ?? err}`);
+        }
+        if (!body || typeof body !== 'object' || !body.id) {
+            throw new EmptyResultError('hf paper', `Hugging Face returned no paper data for "${raw}".`);
+        }
+        const authors = Array.isArray(body.authors)
+            ? body.authors.map((a) => (typeof a === 'object' && a ? (a.name || a.fullname || '') : String(a))).filter(Boolean)
+            : [];
+        const aiKeywords = Array.isArray(body.ai_keywords) ? body.ai_keywords.join(', ') : '';
+        return [{
+            id: String(body.id),
+            title: String(body.title ?? ''),
+            authors: authors.join(', '),
+            publishedAt: String(body.publishedAt ?? '').slice(0, 10),
+            upvotes: body.upvotes != null ? Number(body.upvotes) : null,
+            aiKeywords,
+            summary: String(body.summary ?? ''),
+            aiSummary: String(body.ai_summary ?? ''),
+            url: `${endpoint}/papers/${body.id}`,
+        }];
+    },
+});

package/clis/hf/spaces.js

@@ -0,0 +1,101 @@
+// hf spaces — list top Hugging Face Spaces (gradio / streamlit / static demos).
+//
+// Hits `https://huggingface.co/api/spaces?sort=…&full=true`. Mirrors the shape
+// of `hf models` / `hf datasets`. The Spaces API does not expose `trending` as
+// a sort key (verified live: returns "Invalid sort parameter"), so the allowed
+// sort set is narrower.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const SORT_OPTIONS = ['likes', 'created_at', 'last_modified'];
+const SORT_ALIAS = { lastmodified: 'last_modified', createdat: 'created_at' };
+
+cli({
+    site: 'hf',
+    name: 'spaces',
+    access: 'read',
+    description: 'Top Hugging Face Spaces (likes / created_at / last_modified).',
+    domain: 'huggingface.co',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'sort', type: 'string', default: 'likes', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
+        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter (e.g. "stability", "openai/")' },
+        { name: 'sdk', type: 'string', required: false, help: 'Filter by Space SDK: gradio / streamlit / docker / static' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max spaces (max 100; one API page).' },
+    ],
+    columns: ['rank', 'id', 'author', 'sdk', 'likes', 'tags', 'lastModified', 'url'],
+    func: async (args) => {
+        const sortRaw = String(args.sort ?? 'likes').toLowerCase();
+        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
+        if (!SORT_OPTIONS.includes(sort)) {
+            throw new ArgumentError(`hf spaces sort must be one of ${SORT_OPTIONS.join(', ')}`);
+        }
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('hf spaces limit must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('hf spaces limit must be <= 100');
+        }
+        const sdk = args.sdk == null ? '' : String(args.sdk).trim().toLowerCase();
+        const allowedSdks = new Set(['', 'gradio', 'streamlit', 'docker', 'static']);
+        if (!allowedSdks.has(sdk)) {
+            throw new ArgumentError(`hf spaces sdk must be one of gradio / streamlit / docker / static`);
+        }
+
+        const url = new URL('https://huggingface.co/api/spaces');
+        url.searchParams.set('sort', sort);
+        url.searchParams.set('direction', '-1');
+        url.searchParams.set('limit', String(limit));
+        url.searchParams.set('full', 'true');
+        if (args.search) url.searchParams.set('search', String(args.search));
+        if (sdk) url.searchParams.set('sdk', sdk);
+
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: { Accept: 'application/json', 'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)' },
+            });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`hf spaces request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'hf spaces returned HTTP 429 (rate limited)',
+                'Hugging Face throttles unauthenticated traffic; wait a few seconds and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`hf spaces failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`hf spaces returned malformed JSON: ${err?.message ?? err}`);
+        }
+        const list = Array.isArray(data) ? data : [];
+        if (!list.length) {
+            throw new EmptyResultError('hf spaces', 'No matching spaces on huggingface.co.');
+        }
+        return list.slice(0, limit).map((s, i) => {
+            const id = String(s.id ?? s._id ?? '');
+            const slash = id.indexOf('/');
+            const author = String(s.author ?? (slash > 0 ? id.slice(0, slash) : ''));
+            const tags = Array.isArray(s.tags) ? s.tags.filter((t) => !String(t).startsWith('license:')).slice(0, 10).join(', ') : '';
+            return {
+                rank: i + 1,
+                id,
+                author,
+                sdk: String(s.sdk ?? ''),
+                likes: s.likes != null ? Number(s.likes) : null,
+                tags,
+                lastModified: String(s.lastModified ?? '').slice(0, 10),
+                url: id ? `https://huggingface.co/spaces/${id}` : '',
+            };
+        });
+    },
+});

package/clis/hf/top.js

@@ -31,6 +31,7 @@ function getWeekRange() {
 cli({
     site: 'hf',
     name: 'top',
+    access: 'read',
     description: 'Top upvoted Hugging Face papers',
     domain: 'huggingface.co',
     strategy: Strategy.PUBLIC,
@@ -41,6 +42,7 @@ cli({
         { name: 'date', type: 'str', required: false, help: 'Date (YYYY-MM-DD), defaults to most recent' },
         { name: 'period', type: 'str', default: 'daily', choices: ['daily', 'weekly', 'monthly'], help: 'Time period: daily, weekly, or monthly' },
     ],
+    columns: ['rank', 'id', 'title', 'upvotes', 'authors'],
     footerExtra: (kwargs) => {
         if (kwargs._footerDate)
             return kwargs._footerDate;