@jackwener/opencli 1.7.12 → 1.7.13

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

@@ -42,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;

package/clis/homebrew/cask.js

@@ -0,0 +1,39 @@
+// homebrew cask — fetch a single Homebrew cask's metadata.
+//
+// Hits `https://formulae.brew.sh/api/cask/<token>.json`. Returns one row for
+// the macOS/.dmg-style package: canonical token, friendly name, version,
+// homepage, deprecated / disabled flags, download URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { BREW_BASE, brewFetch, requireToken } from './utils.js';
+
+cli({
+    site: 'homebrew',
+    name: 'cask',
+    access: 'read',
+    description: 'Fetch a Homebrew cask\'s metadata (version, homepage, deprecation, download URL)',
+    domain: 'formulae.brew.sh',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'token', positional: true, required: true, help: 'Cask token (e.g. "firefox", "visual-studio-code", "google-chrome")' },
+    ],
+    columns: ['cask', 'tap', 'name', 'version', 'description', 'homepage', 'deprecated', 'disabled', 'download', 'url'],
+    func: async (args) => {
+        const token = requireToken(args.token, 'token');
+        const url = `${BREW_BASE}/cask/${encodeURIComponent(token)}.json`;
+        const body = await brewFetch(url, 'homebrew cask');
+        const friendly = Array.isArray(body?.name) ? body.name.filter(Boolean).join(', ') : String(body?.name ?? '').trim();
+        return [{
+            cask: String(body?.token ?? token).trim(),
+            tap: String(body?.tap ?? '').trim(),
+            name: friendly,
+            version: String(body?.version ?? '').trim(),
+            description: String(body?.desc ?? '').trim(),
+            homepage: String(body?.homepage ?? '').trim(),
+            deprecated: Boolean(body?.deprecated),
+            disabled: Boolean(body?.disabled),
+            download: String(body?.url ?? '').trim(),
+            url: `https://formulae.brew.sh/cask/${encodeURIComponent(token)}`,
+        }];
+    },
+});

package/clis/homebrew/formula.js

@@ -0,0 +1,41 @@
+// homebrew formula — fetch a single Homebrew core formula's metadata.
+//
+// Hits `https://formulae.brew.sh/api/formula/<name>.json`. Returns one row:
+// canonical name, latest stable version, license, dependencies, deprecated /
+// disabled flags, homepage, source tarball URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { BREW_BASE, brewFetch, requireToken } from './utils.js';
+
+cli({
+    site: 'homebrew',
+    name: 'formula',
+    access: 'read',
+    description: 'Fetch a Homebrew formula\'s metadata (version, license, deps, deprecation, source)',
+    domain: 'formulae.brew.sh',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'Formula name (e.g. "wget", "gcc@13", "imagemagick")' },
+    ],
+    columns: ['formula', 'tap', 'version', 'license', 'description', 'homepage', 'dependencies', 'deprecated', 'disabled', 'source', 'url'],
+    func: async (args) => {
+        const name = requireToken(args.name, 'formula');
+        const url = `${BREW_BASE}/formula/${encodeURIComponent(name)}.json`;
+        const body = await brewFetch(url, 'homebrew formula');
+        const deps = Array.isArray(body?.dependencies) ? body.dependencies.filter(Boolean) : [];
+        const stableUrl = String(body?.urls?.stable?.url ?? '').trim();
+        return [{
+            formula: String(body?.name ?? name).trim(),
+            tap: String(body?.tap ?? '').trim(),
+            version: String(body?.versions?.stable ?? '').trim(),
+            license: String(body?.license ?? '').trim(),
+            description: String(body?.desc ?? '').trim(),
+            homepage: String(body?.homepage ?? '').trim(),
+            dependencies: deps.join(', '),
+            deprecated: Boolean(body?.deprecated),
+            disabled: Boolean(body?.disabled),
+            source: stableUrl,
+            url: `https://formulae.brew.sh/formula/${encodeURIComponent(name)}`,
+        }];
+    },
+});

package/clis/homebrew/popular.js

@@ -0,0 +1,54 @@
+// homebrew popular — list the most-installed Homebrew formulae or casks.
+//
+// Hits `https://formulae.brew.sh/api/analytics/(install|cask-install)/<window>.json`.
+// Anonymous-aggregated install counts published by Homebrew themselves;
+// rows round-trip into `homebrew formula` / `homebrew cask` via the `token`
+// column. The 30/90/365-day windows are the only ones the analytics endpoint
+// publishes — anything else 404s upstream.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { BREW_BASE, brewFetch, parseInstallCount, requireBoundedInt, requireOneOf } from './utils.js';
+
+const TYPES = ['formula', 'cask'];
+const WINDOWS = ['30d', '90d', '365d'];
+
+cli({
+    site: 'homebrew',
+    name: 'popular',
+    access: 'read',
+    description: 'List most-installed Homebrew formulae or casks (Homebrew\'s analytics ranking)',
+    domain: 'formulae.brew.sh',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'type', default: 'formula', help: `Package type (${TYPES.join(' / ')})` },
+        { name: 'window', default: '30d', help: `Time window (${WINDOWS.join(' / ')})` },
+        { name: 'limit', type: 'int', default: 30, help: 'Max rows (1-500)' },
+    ],
+    columns: ['rank', 'token', 'type', 'installs', 'percent', 'window', 'url'],
+    func: async (args) => {
+        const type = requireOneOf(args.type, TYPES, 'type');
+        const window = requireOneOf(args.window, WINDOWS, 'window');
+        const limit = requireBoundedInt(args.limit, 30, 500);
+        const path = type === 'cask' ? 'cask-install' : 'install';
+        const url = `${BREW_BASE}/analytics/${path}/${window}.json`;
+        const body = await brewFetch(url, 'homebrew popular');
+        const items = Array.isArray(body?.items) ? body.items : [];
+        if (!items.length) {
+            throw new EmptyResultError('homebrew popular', `Homebrew analytics returned no items for ${type}/${window}.`);
+        }
+        return items.slice(0, limit).map((row, i) => {
+            const token = String(type === 'cask' ? row.cask : row.formula ?? '').trim();
+            const detailPath = type === 'cask' ? 'cask' : 'formula';
+            return {
+                rank: row.number != null ? Number(row.number) : i + 1,
+                token,
+                type,
+                installs: parseInstallCount(row.count),
+                percent: row.percent != null ? Number(row.percent) : null,
+                window,
+                url: token ? `https://formulae.brew.sh/${detailPath}/${encodeURIComponent(token)}` : '',
+            };
+        });
+    },
+});

package/clis/homebrew/utils.js

@@ -0,0 +1,100 @@
+// Shared helpers for the Homebrew adapters.
+//
+// Hits the public, unauthenticated `formulae.brew.sh/api` JSON endpoints
+// (served as static files from GitHub Pages, regenerated daily). No auth.
+// Formula / cask tokens are lowercase ASCII + `-_.+@` per Homebrew's own
+// validation; they round-trip into `homebrew formula` / `homebrew cask`.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const BREW_BASE = 'https://formulae.brew.sh/api';
+const UA = 'opencli-homebrew-adapter (+https://github.com/jackwener/opencli)';
+
+// Homebrew formula / cask tokens — letters / digits / `_-.+@` (`gcc@13`,
+// `imagemagick@6`, `c++`, `0-ad`, `php-cs-fixer`).
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`homebrew ${label} cannot be empty`);
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`homebrew ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`homebrew ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireToken(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError(`homebrew ${label} is required (e.g. "wget", "gcc@13", "firefox")`);
+    }
+    if (s.length > 100 || !TOKEN.test(s)) {
+        throw new ArgumentError(
+            `homebrew ${label} "${value}" is not a valid token`,
+            'Use letters / digits / "_-.+@", starting with a letter or digit (max 100 chars).',
+        );
+    }
+    return s;
+}
+
+export function requireOneOf(value, allowed, label) {
+    const s = String(value ?? '').trim().toLowerCase();
+    if (!s) throw new ArgumentError(`homebrew ${label} is required`);
+    if (!allowed.includes(s)) {
+        throw new ArgumentError(
+            `homebrew ${label} "${value}" is not supported`,
+            `Allowed: ${allowed.join(', ')}.`,
+        );
+    }
+    return s;
+}
+
+export async function brewFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that formulae.brew.sh is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Homebrew API returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Homebrew throttles bursts; wait a few seconds and retry.',
+        );
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+/** Coerce a count value (which Homebrew analytics serves as `"139,972"`) to a plain number. */
+export function parseInstallCount(value) {
+    if (value == null) return null;
+    const s = String(value).replace(/,/g, '').trim();
+    if (!s) return null;
+    const n = Number(s);
+    return Number.isFinite(n) ? n : null;
+}

package/clis/hupu/__fixtures__/hot-home.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="zh-CN"><head><title>虎扑社区</title></head><body>
+<div id="container"><div class="bbs-index-web">
+<nav>
+<a href="/639999999.html"><span class="t-title">导航里的 thread-shaped phantom 链接</span></a>
+</nav>
+<div class="text-list-model">
+<div class="list-item-wrap"><div class="list-title">步行街</div></div>
+
+<div class="list-item-wrap"><div class="list-wrap"><div class="list-item">
+<div class="t-info">
+<a href="/639088523.html" target="_blank" class=" hot"><span class="t-title">网友曝三亚4只皮皮虾收费1035，官方凌晨通报</span></a>
+<span class="t-lights">50亮</span>
+<span class="t-replies">359回复</span>
+</div>
+<div class="t-label"><a href="/forum">步行街主干道</a></div>
+</div></div></div>
+
+<div class="list-item-wrap"><div class="list-wrap"><div class="list-item">
+<div class="t-info">
+<a href="/639095236.html" target="_blank" class=" false"><span class="t-title">[流言板]市监局称4只皮皮虾1035元价格合规</span></a>
+<span class="t-lights">48亮</span>
+<span class="t-replies">128回复</span>
+</div>
+<div class="t-label"><a href="/forum">步行街主干道</a></div>
+</div></div></div>
+
+<div class="list-item-wrap"><div class="list-wrap"><div class="list-item">
+<div class="t-info">
+<a href="/639094866.html" target="_blank" class=" false"><span class="t-title">印度顶层婆罗门家庭的微奢晚餐，大家觉得怎么样？</span></a>
+<span class="t-lights">1.2万亮</span>
+<span class="t-replies">5.8万回复</span>
+</div>
+<div class="t-label"><a href="/forum">步行街主干道</a></div>
+</div></div></div>
+
+<div class="list-item-wrap"><div class="list-wrap"><div class="list-item">
+<div class="t-info">
+<a href="/639100001.html" target="_blank" class=" hot"><span class="t-title">湖人战胜勇士拿下连胜</span></a>
+<span class="t-lights">0亮</span>
+<span class="t-replies">0回复</span>
+</div>
+<div class="t-label"><a href="/forum">NBA湿乎乎的话题</a></div>
+</div></div></div>
+
+<div class="list-item-wrap"><div class="list-wrap"><div class="list-item">
+<div class="t-info">
+<a href="/639100002.html" target="_blank" class=" false"><span class="t-title">无 lights 的标题（少见但要兼容）</span></a>
+
+<span class="t-replies">20回复</span>
+</div>
+<div class="t-label"><a href="/forum">电竞</a></div>
+</div></div></div>
+
+<div class="list-item-wrap"><div class="list-wrap"><div class="list-item">
+<div class="t-info">
+<a href="/639100003.html" target="_blank" class=" hot"><span class="t-title">另一个 hot 帖子</span></a>
+<span class="t-lights">100亮</span>
+<span class="t-replies">200回复</span>
+</div>
+<div class="t-label"><a href="/forum">国际足球</a></div>
+</div></div></div>
+</div>
+</div></div></body></html>

package/clis/hupu/detail.js

@@ -8,7 +8,6 @@ cli({
     domain: 'bbs.hupu.com',
     strategy: Strategy.PUBLIC,
     browser: true,
-    navigateBefore: false,
     args: [
         {
             name: 'tid',