@jackwener/opencli 1.7.11 → 1.7.13

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

@@ -3,11 +3,11 @@ import { getHupuThreadUrl, readHupuNextData, stripHtml } from './utils.js';
 cli({
     site: 'hupu',
     name: 'detail',
+    access: 'read',
     description: '获取虎扑帖子详情 (使用Next.js JSON数据)',
     domain: 'bbs.hupu.com',
     strategy: Strategy.PUBLIC,
     browser: true,
-    navigateBefore: false,
     args: [
         {
             name: 'tid',

package/clis/hupu/hot.js

@@ -1,40 +1,163 @@
-import { cli } from '@jackwener/opencli/registry';
-cli({
+// Hupu hot/home threads — public SSR HTML scrape via in-page DOM walk.
+//
+// Replaces the legacy `pipeline:[]` + `documentElement.outerHTML` regex,
+// which had two anti-pattern problems:
+//   1. Regex against `outerHTML` is brittle to whitespace / attribute order
+//      shifts and silently drops rows when the markup wobbles.
+//   2. The regex captured every 9-digit thread anchor on the page, not just
+//      the rows inside `.t-info` containers — `.list-item` rows and pure
+//      navigation links got conflated.
+//
+// New behavior:
+//   - `func` form with `Strategy.PUBLIC` + `browser:true` (consistent with
+//     other public hupu adapters).
+//   - Upfront `--limit` validation: must be a positive integer ≤ 100, no
+//     silent clamp; `ArgumentError` on bad input.
+//   - DOM walk via `querySelectorAll('.t-info')` — same scope hupu's web
+//     client renders, so the row count matches what the human sees.
+//   - Enriched columns: `lights` (亮 count, int|null), `replies` (回复
+//     count, int|null), `forum` (sub-section name from sibling `.t-label`),
+//     `is_hot` (whether the page tagged the row with `class=" hot"` —
+//     transparent surfacing of hupu's own hot marker without filtering, so
+//     existing callers see the same row order).
+//   - Empty page → `EmptyResultError`, never silent `[]`.
+//   - Pure extraction (`extractHupuHotRowsFromDoc`) is a Node-side export
+//     so JSDOM-against-frozen-fixture tests can call it directly while the
+//     live IIFE embeds the same function via `${fn.toString()}` (mirrors
+//     dianping #1313 pattern).
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const HUPU_HOST = 'https://bbs.hupu.com';
+export const HOT_LIMIT_DEFAULT = 20;
+export const HOT_LIMIT_MAX = 100;
+
+export function normalizeHotLimit(raw) {
+    if (raw === undefined || raw === null || raw === '') {
+        return HOT_LIMIT_DEFAULT;
+    }
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1 || n > HOT_LIMIT_MAX) {
+        throw new ArgumentError(
+            `--limit must be a positive integer in [1, ${HOT_LIMIT_MAX}], got ${JSON.stringify(raw)}`,
+        );
+    }
+    return n;
+}
+
+// Parse hupu count strings like "50亮", "359回复", "1.2万" → typed int.
+// Returns null when the input does not look like a count we can read.
+// `0` is preserved (real value), `null` means "we could not extract it"
+// — never use `0` as an unknown sentinel here.
+export function parseHupuCount(raw) {
+    if (raw === undefined || raw === null) return null;
+    const text = String(raw).trim();
+    if (!text) return null;
+    const match = text.match(/^([0-9]+(?:\.[0-9]+)?)\s*(万)?/);
+    if (!match) return null;
+    const num = parseFloat(match[1]);
+    if (!Number.isFinite(num)) return null;
+    return Math.round(match[2] === '万' ? num * 10000 : num);
+}
+
+// Pure extractor: walks `.t-info` containers and returns at most `limit`
+// rows. `doc` is a Document (live `document` in browser, JSDOM document
+// in tests). `parseCount` is injected so the same function works in both
+// contexts (in-browser eval embeds it via `${fn.toString()}`, JSDOM tests
+// pass the imported reference).
+export function extractHupuHotRowsFromDoc(doc, limit, parseCount) {
+    const out = [];
+    const items = doc.querySelectorAll('.t-info');
+    for (let i = 0; i < items.length && out.length < limit; i += 1) {
+        const info = items[i];
+        const anchor = info.querySelector('a[href]');
+        if (!anchor) continue;
+        const href = anchor.getAttribute('href') || '';
+        const tidMatch = href.match(/^\/(\d{9})\.html$/);
+        if (!tidMatch) continue;
+        const tid = tidMatch[1];
+        const titleEl = anchor.querySelector('.t-title');
+        const title = titleEl ? (titleEl.textContent || '').trim() : '';
+        if (!title) continue;
+        const classes = (anchor.getAttribute('class') || '').split(/\s+/).filter(Boolean);
+        const isHot = classes.includes('hot');
+        const lightsEl = info.querySelector('.t-lights');
+        const repliesEl = info.querySelector('.t-replies');
+        const lights = parseCount(lightsEl ? lightsEl.textContent : null);
+        const replies = parseCount(repliesEl ? repliesEl.textContent : null);
+        // forum label sits beside `.t-info` inside `.list-item`
+        const listItem = info.parentElement;
+        const labelEl = listItem ? listItem.querySelector('.t-label a') : null;
+        const forum = labelEl ? (labelEl.textContent || '').trim() : '';
+        out.push({
+            rank: out.length + 1,
+            tid,
+            title,
+            lights,
+            replies,
+            forum,
+            is_hot: isHot,
+            url: `${HUPU_HOST}/${tid}.html`,
+        });
+    }
+    return out;
+}
+
+export function buildHotScript(limit) {
+    return `
+(async () => {
+  const HUPU_HOST = ${JSON.stringify(HUPU_HOST)};
+  ${parseHupuCount.toString()}
+  ${extractHupuHotRowsFromDoc.toString()}
+  // Wait briefly for .t-info rows to render in case the page is still
+  // hydrating; bbs.hupu.com is mostly SSR so this returns fast.
+  const start = Date.now();
+  while (document.querySelectorAll('.t-info').length === 0 && Date.now() - start < 5000) {
+    await new Promise(r => setTimeout(r, 100));
+  }
+  return extractHupuHotRowsFromDoc(document, ${JSON.stringify(limit)}, parseHupuCount);
+})()
+`;
+}
+
+async function getHupuHot(page, args) {
+    const limit = normalizeHotLimit(args.limit);
+    await page.goto(`${HUPU_HOST}/`, { waitUntil: 'load', settleMs: 1000 });
+    let rows;
+    try {
+        rows = await page.evaluate(buildHotScript(limit));
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(
+            `Failed to read hupu hot threads: ${message}`,
+            'bbs.hupu.com may be unreachable or its markup may have changed',
+        );
+    }
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new EmptyResultError(
+            'hupu/hot',
+            'No threads found on bbs.hupu.com — page structure may have changed',
+        );
+    }
+    return rows;
+}
+
+export const hotCommand = cli({
     site: 'hupu',
     name: 'hot',
-    description: '虎扑热门帖子',
+    access: 'read',
+    description: '虎扑首页热门帖子（含 lights / replies / forum / is_hot 列）',
     domain: 'bbs.hupu.com',
+    strategy: Strategy.PUBLIC,
+    browser: true,
     args: [
-        { name: 'limit', type: 'int', default: 20, help: 'Number of hot posts' },
-    ],
-    columns: ['rank', 'title', 'url'],
-    pipeline: [
-        { navigate: 'https://bbs.hupu.com/' },
-        { evaluate: `(async () => {
-  // 从HTML中提取帖子信息（适配新的HTML结构）
-  const html = document.documentElement.outerHTML;
-  const posts = [];
-
-  // 匹配当前虎扑页面结构的正则表达式
-  // 结构: <a href="/638249612.html"...><span class="t-title">标题</span></a>
-  const regex = /<a[^>]*href="\\/(\\d{9})\\.html"[^>]*><span[^>]*class="t-title"[^>]*>([^<]+)<\\/span><\\/a>/g;
-  let match;
-
-  while ((match = regex.exec(html)) !== null && posts.length < \${{ args.limit }}) {
-    posts.push({
-      tid: match[1],
-      title: match[2].trim()
-    });
-  }
-
-  return posts;
-})()
-` },
-        { map: {
-                rank: '${{ index + 1 }}',
-                title: '${{ item.title }}',
-                url: 'https://bbs.hupu.com/${{ item.tid }}.html',
-            } },
-        { limit: '${{ args.limit }}' },
+        { name: 'limit', type: 'int', default: HOT_LIMIT_DEFAULT, help: `Number of threads (1-${HOT_LIMIT_MAX})` },
     ],
+    columns: ['rank', 'tid', 'title', 'lights', 'replies', 'forum', 'is_hot', 'url'],
+    func: getHupuHot,
 });
+
+export const __test__ = {
+    buildHotScript,
+};