@jackwener/opencli 1.7.11 → 1.7.13

package/clis/rfc/rfc.test.js

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './rfc.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('rfc rfc adapter', () => {
+    const cmd = getRegistry().get('rfc/rfc');
+
+    it('rejects malformed RFC numbers before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ number: 'abc' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ number: 0 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ number: -5 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ number: 1000000 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 404 to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('not found', { status: 404 })));
+        await expect(cmd.func({ number: 999998 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('rate limited', { status: 429 })));
+        await expect(cmd.func({ number: 9000 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('flattens authors + group, normalises space-separated date, and emits rfcEditorUrl', async () => {
+        const doc = {
+            name: 'rfc9000',
+            title: 'QUIC: A UDP-Based Multiplexed and Secure Transport',
+            state: 'Published',
+            std_level: 'Proposed Standard',
+            group: { name: 'QUIC', type: 'WG' },
+            pages: 151,
+            time: '2022-02-19 08:46:51',
+            authors: [
+                { name: 'Jana Iyengar', email: 'jri@example' },
+                { name: 'Martin Thomson', email: 'mt@example' },
+            ],
+            abstract: 'This document defines QUIC.',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(doc), { status: 200 })));
+
+        const rows = await cmd.func({ number: 9000 });
+        expect(rows[0]).toMatchObject({
+            rfc: 9000,
+            title: 'QUIC: A UDP-Based Multiplexed and Secure Transport',
+            stdLevel: 'Proposed Standard',
+            group: 'QUIC',
+            groupType: 'WG',
+            pages: 151,
+            published: '2022-02-19',
+            authors: 'Jana Iyengar, Martin Thomson',
+            rfcEditorUrl: 'https://www.rfc-editor.org/rfc/rfc9000',
+            url: 'https://datatracker.ietf.org/doc/rfc9000/',
+        });
+    });
+
+    it('accepts "rfc<N>" prefix as a courtesy', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            name: 'rfc791', title: 'Internet Protocol', authors: [], group: {},
+        }), { status: 200 })));
+        const rows = await cmd.func({ number: 'rfc791' });
+        expect(rows[0].rfc).toBe(791);
+    });
+});

package/clis/rfc/utils.js

@@ -0,0 +1,72 @@
+// Shared helpers for the IETF RFC adapter.
+//
+// datatracker.ietf.org publishes a free, unauthenticated REST API. The
+// `/doc/<name>/doc.json` endpoint returns rich metadata for any IETF document
+// (RFCs, internet drafts, etc.). Docs: https://datatracker.ietf.org/api/
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const RFC_BASE = 'https://datatracker.ietf.org';
+const UA = 'opencli-rfc-adapter (+https://github.com/jackwener/opencli)';
+
+export function requireRfcNumber(value) {
+    const raw = value;
+    if (raw == null || String(raw).trim() === '') {
+        throw new ArgumentError(
+            'rfc number is required (e.g. 9000, 791, 2616)',
+            'Pass the integer RFC number; do not include the "rfc" prefix.',
+        );
+    }
+    // Accept "9000" or 9000 or "rfc9000" as a courtesy.
+    const s = String(raw).trim().toLowerCase().replace(/^rfc/, '');
+    const n = Number.parseInt(s, 10);
+    if (!Number.isInteger(n) || n <= 0 || String(n) !== s) {
+        throw new ArgumentError(
+            `rfc number "${value}" is not a valid RFC number`,
+            'Pass a positive integer (e.g. 9000, 791, 2616).',
+        );
+    }
+    if (n > 999999) {
+        throw new ArgumentError('rfc number must be <= 999999');
+    }
+    return n;
+}
+
+export async function rfcFetch(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 datatracker.ietf.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `IETF datatracker returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(`${label} returned HTTP 429 (rate limited)`);
+    }
+    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;
+}
+
+// IETF datatracker timestamps are like "2022-02-19 08:46:51" (no T, no Z)
+// or ISO with offset like "2016-07-08T21:03:52+00:00". Normalise to YYYY-MM-DD.
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    // Take the first 10 chars only if they form a YYYY-MM-DD prefix.
+    if (/^\d{4}-\d{2}-\d{2}/.test(s)) return s.slice(0, 10);
+    return null;
+}

package/clis/rubygems/gem.js

@@ -0,0 +1,42 @@
+// rubygems gem — fetch a single gem's metadata from RubyGems.org.
+//
+// Hits `https://rubygems.org/api/v1/gems/<name>.json`. Returns a one-row
+// projection: latest version + release date, lifetime / version downloads,
+// license(s), author(s), homepage, source, bug tracker, short info.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { GEMS_BASE, gemsFetch, requireGemName, trimDate } from './utils.js';
+
+cli({
+    site: 'rubygems',
+    name: 'gem',
+    access: 'read',
+    description: 'Fetch a RubyGems.org gem\'s metadata (version, downloads, license, links)',
+    domain: 'rubygems.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'Gem name (e.g. "rails", "sidekiq")' },
+    ],
+    columns: ['gem', 'version', 'releasedAt', 'downloads', 'versionDownloads', 'license', 'authors', 'homepage', 'source', 'bugs', 'info', 'url'],
+    func: async (args) => {
+        const name = requireGemName(args.name);
+        const url = `${GEMS_BASE}/gems/${encodeURIComponent(name)}.json`;
+        const body = await gemsFetch(url, 'rubygems gem');
+        const licenses = Array.isArray(body?.licenses) ? body.licenses.filter(Boolean).join(', ') : '';
+        const meta = body?.metadata ?? {};
+        return [{
+            gem: String(body?.name ?? name).trim(),
+            version: String(body?.version ?? '').trim(),
+            releasedAt: trimDate(body?.version_created_at),
+            downloads: body?.downloads != null ? Number(body.downloads) : null,
+            versionDownloads: body?.version_downloads != null ? Number(body.version_downloads) : null,
+            license: licenses,
+            authors: String(body?.authors ?? '').trim(),
+            homepage: String(body?.homepage_uri ?? '').trim(),
+            source: String(body?.source_code_uri ?? meta.source_code_uri ?? '').trim(),
+            bugs: String(body?.bug_tracker_uri ?? meta.bug_tracker_uri ?? '').trim(),
+            info: String(body?.info ?? '').trim(),
+            url: String(body?.project_uri ?? `https://rubygems.org/gems/${name}`).trim(),
+        }];
+    },
+});

package/clis/rubygems/search.js

@@ -0,0 +1,47 @@
+// rubygems search — search the RubyGems.org public index.
+//
+// Hits `https://rubygems.org/api/v1/search.json?query=…&page=1`. Returns an
+// agent-useful projection: gem name (round-trips into `rubygems gem`), latest
+// version, lifetime downloads, license(s), author(s), short info, project URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { GEMS_BASE, gemsFetch, requireBoundedInt, requireString } from './utils.js';
+
+cli({
+    site: 'rubygems',
+    name: 'search',
+    access: 'read',
+    description: 'Search RubyGems.org gems by keyword',
+    domain: 'rubygems.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "rails", "redis")' },
+        { name: 'limit', type: 'int', default: 30, help: 'Max gems (1-100, single RubyGems page)' },
+    ],
+    columns: ['rank', 'gem', 'version', 'downloads', 'license', 'authors', 'info', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 30, 100);
+        const url = `${GEMS_BASE}/search.json?query=${encodeURIComponent(query)}&page=1`;
+        const body = await gemsFetch(url, 'rubygems search');
+        const list = Array.isArray(body) ? body : [];
+        if (!list.length) {
+            throw new EmptyResultError('rubygems search', `No gems matched "${query}".`);
+        }
+        return list.slice(0, limit).map((g, i) => {
+            const name = String(g.name ?? '').trim();
+            const licenses = Array.isArray(g.licenses) ? g.licenses.filter(Boolean).join(', ') : '';
+            return {
+                rank: i + 1,
+                gem: name,
+                version: String(g.version ?? '').trim(),
+                downloads: g.downloads != null ? Number(g.downloads) : null,
+                license: licenses,
+                authors: String(g.authors ?? '').trim(),
+                info: String(g.info ?? '').trim(),
+                url: name ? `https://rubygems.org/gems/${name}` : '',
+            };
+        });
+    },
+});

package/clis/rubygems/utils.js

@@ -0,0 +1,86 @@
+// Shared helpers for the RubyGems.org adapters.
+//
+// Hits the public, unauthenticated `rubygems.org/api/v1` REST endpoints. No
+// auth required for read-only metadata; the API is friendly to anonymous CLI
+// traffic. Gem names follow the RubyGems convention: lowercase ASCII +
+// `-_.`, 1-100 chars, must start with a letter or digit.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const GEMS_BASE = 'https://rubygems.org/api/v1';
+const UA = 'opencli-rubygems-adapter (+https://github.com/jackwener/opencli)';
+
+// RubyGems gem name pattern (mirrors the rubygems-server validation).
+const GEM_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`rubygems ${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(`rubygems ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`rubygems ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireGemName(value) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError('rubygems gem name is required (e.g. "rails", "sidekiq")');
+    }
+    if (s.length > 100 || !GEM_NAME.test(s)) {
+        throw new ArgumentError(
+            `rubygems gem "${value}" is not a valid gem name`,
+            'Use letters / digits / "._-", starting with a letter or digit (max 100 chars).',
+        );
+    }
+    return s;
+}
+
+export async function gemsFetch(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 rubygems.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `RubyGems returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'RubyGems 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;
+}
+
+/** Trim "2026-03-24T20:27:42.098Z" → "2026-03-24T20:27:42Z" so timestamps share a uniform precision. */
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    const noFrac = s.replace(/\.\d+/, '');
+    return noFrac.endsWith('Z') ? noFrac : `${noFrac}Z`;
+}

package/clis/sinablog/article.js

@@ -3,6 +3,7 @@ import { loadSinaBlogArticle } from './utils.js';
 cli({
     site: 'sinablog',
     name: 'article',
+    access: 'read',
     description: '获取新浪博客单篇文章详情',
     domain: 'blog.sina.com.cn',
     strategy: Strategy.COOKIE,

package/clis/sinablog/hot.js

@@ -3,6 +3,7 @@ import { loadSinaBlogHot } from './utils.js';
 cli({
     site: 'sinablog',
     name: 'hot',
+    access: 'read',
     description: '获取新浪博客热门文章/推荐',
     domain: 'blog.sina.com.cn',
     strategy: Strategy.COOKIE,

package/clis/sinablog/search.js

@@ -38,6 +38,7 @@ async function searchSinaBlog(keyword, limit) {
 cli({
     site: 'sinablog',
     name: 'search',
+    access: 'read',
     description: '搜索新浪博客文章（通过新浪搜索）',
     domain: 'blog.sina.com.cn',
     strategy: Strategy.PUBLIC,

package/clis/sinablog/user.js

@@ -3,6 +3,7 @@ import { loadSinaBlogUser } from './utils.js';
 cli({
     site: 'sinablog',
     name: 'user',
+    access: 'read',
     description: '获取新浪博客用户的文章列表',
     domain: 'blog.sina.com.cn',
     strategy: Strategy.COOKIE,

package/clis/sinafinance/news.js

@@ -25,6 +25,7 @@ function stripHtml(html) {
 cli({
     site: 'sinafinance',
     name: 'news',
+    access: 'read',
     description: '新浪财经 7x24 小时实时快讯',
     domain: 'app.cj.sina.com.cn',
     strategy: Strategy.PUBLIC,

package/clis/sinafinance/rolling-news.js

@@ -5,6 +5,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'sinafinance',
     name: 'rolling-news',
+    access: 'read',
     description: '新浪财经滚动新闻',
     domain: 'finance.sina.com.cn/roll',
     strategy: Strategy.COOKIE,

package/clis/sinafinance/stock-rank.js

@@ -5,6 +5,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'sinafinance',
     name: 'stock-rank',
+    access: 'read',
     description: '新浪财经热搜榜',
     domain: 'finance.sina.cn',
     strategy: Strategy.COOKIE,

package/clis/sinafinance/stock.js

@@ -53,6 +53,7 @@ function fmtMktCap(val) {
 cli({
     site: 'sinafinance',
     name: 'stock',
+    access: 'read',
     description: '新浪财经行情（A股/港股/美股）',
     domain: 'suggest3.sinajs.cn,hq.sinajs.cn',
     strategy: Strategy.PUBLIC,

package/clis/smzdm/search.js

@@ -9,6 +9,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'smzdm',
     name: 'search',
+    access: 'read',
     description: '什么值得买搜索好价',
     domain: 'www.smzdm.com',
     strategy: Strategy.COOKIE,

package/clis/spotify/spotify.js

@@ -106,6 +106,7 @@ function openBrowser(url) {
 cli({
     site: 'spotify',
     name: 'auth',
+    access: 'write',
     description: 'Authenticate with Spotify (OAuth — run once)',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -172,6 +173,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'status',
+    access: 'read',
     description: 'Show current playback status',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -193,6 +195,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'play',
+    access: 'write',
     description: 'Resume playback or search and play a track/artist',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -211,6 +214,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'pause',
+    access: 'write',
     description: 'Pause playback',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -221,6 +225,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'next',
+    access: 'write',
     description: 'Skip to next track',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -231,6 +236,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'prev',
+    access: 'write',
     description: 'Skip to previous track',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -241,6 +247,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'volume',
+    access: 'write',
     description: 'Set playback volume (0-100)',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -257,6 +264,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'search',
+    access: 'read',
     description: 'Search for tracks',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -277,6 +285,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'queue',
+    access: 'write',
     description: 'Add a track to the playback queue',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -291,6 +300,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'shuffle',
+    access: 'write',
     description: 'Toggle shuffle on/off',
     strategy: Strategy.PUBLIC,
     browser: false,
@@ -304,6 +314,7 @@ cli({
 cli({
     site: 'spotify',
     name: 'repeat',
+    access: 'write',
     description: 'Set repeat mode (off / track / context)',
     strategy: Strategy.PUBLIC,
     browser: false,

package/clis/stackoverflow/bounties.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'stackoverflow',
     name: 'bounties',
+    access: 'read',
     description: 'Active bounties on Stack Overflow',
     domain: 'stackoverflow.com',
     strategy: Strategy.PUBLIC,
@@ -9,17 +10,24 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 10, help: 'Max number of results' },
     ],
-    columns: ['bounty', 'title', 'score', 'answers', 'url'],
+    columns: ['rank', 'id', 'bounty', 'title', 'score', 'answers', 'views', 'is_answered', 'tags', 'author', 'creation_date', 'url'],
     pipeline: [
         { fetch: {
-                url: 'https://api.stackexchange.com/2.3/questions/featured?order=desc&sort=activity&site=stackoverflow',
+                url: 'https://api.stackexchange.com/2.3/questions/featured?order=desc&sort=activity&site=stackoverflow&pagesize=${{ args.limit }}',
             } },
         { select: 'items' },
         { map: {
-                title: '${{ item.title }}',
+                rank: '${{ index + 1 }}',
+                id: '${{ item.question_id }}',
                 bounty: '${{ item.bounty_amount }}',
+                title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 answers: '${{ item.answer_count }}',
+                views: '${{ item.view_count }}',
+                is_answered: '${{ item.is_answered }}',
+                tags: `\${{ item.tags | join(', ') }}`,
+                author: '${{ item.owner.display_name }}',
+                creation_date: '${{ item.creation_date }}',
                 url: '${{ item.link }}',
             } },
         { limit: '${{ args.limit }}' },

package/clis/stackoverflow/hot.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'stackoverflow',
     name: 'hot',
+    access: 'read',
     description: 'Hot Stack Overflow questions',
     domain: 'stackoverflow.com',
     strategy: Strategy.PUBLIC,
@@ -9,14 +10,21 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 10, help: 'Max number of results' },
     ],
-    columns: ['title', 'score', 'answers', 'url'],
+    columns: ['rank', 'id', 'title', 'score', 'answers', 'views', 'is_answered', 'tags', 'author', 'creation_date', 'url'],
     pipeline: [
-        { fetch: { url: 'https://api.stackexchange.com/2.3/questions?order=desc&sort=hot&site=stackoverflow' } },
+        { fetch: { url: 'https://api.stackexchange.com/2.3/questions?order=desc&sort=hot&site=stackoverflow&pagesize=${{ args.limit }}' } },
         { select: 'items' },
         { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.question_id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 answers: '${{ item.answer_count }}',
+                views: '${{ item.view_count }}',
+                is_answered: '${{ item.is_answered }}',
+                tags: `\${{ item.tags | join(', ') }}`,
+                author: '${{ item.owner.display_name }}',
+                creation_date: '${{ item.creation_date }}',
                 url: '${{ item.link }}',
             } },
         { limit: '${{ args.limit }}' },