@jackwener/opencli 1.7.11 → 1.7.13

package/clis/rest-countries/country.js

@@ -0,0 +1,65 @@
+// rest-countries country — look up a country by common / official name.
+//
+// REST Countries' `name/<query>` endpoint matches as substring across both
+// common and official names; multiple matches are returned (e.g. "guinea"
+// matches Guinea, Guinea-Bissau, Equatorial Guinea, Papua New Guinea).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    COUNTRY_FIELDS,
+    REST_COUNTRIES_BASE,
+    projectCountry,
+    requireBoundedInt,
+    requireString,
+    restCountriesFetch,
+} from './utils.js';
+
+cli({
+    site: 'rest-countries',
+    name: 'country',
+    access: 'read',
+    description: 'Look up countries by name (common / official, substring match)',
+    domain: 'restcountries.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'Country name (e.g. "japan", "united kingdom")' },
+        { name: 'limit', type: 'int', default: 25, help: 'Max rows (1-250)' },
+    ],
+    columns: [
+        'rank',
+        'commonName',
+        'officialName',
+        'cca2',
+        'cca3',
+        'ccn3',
+        'capital',
+        'region',
+        'subregion',
+        'population',
+        'area',
+        'languages',
+        'currencies',
+        'latitude',
+        'longitude',
+        'timezones',
+        'independent',
+        'unMember',
+        'landlocked',
+        'flag',
+        'url',
+    ],
+    func: async (args) => {
+        const name = requireString(args.name, 'name');
+        const limit = requireBoundedInt(args.limit, 25, 250);
+        const url = `${REST_COUNTRIES_BASE}/name/${encodeURIComponent(name)}?fields=${COUNTRY_FIELDS}`;
+        const body = await restCountriesFetch(url, 'rest-countries country');
+        const list = Array.isArray(body) ? body : [];
+        if (!list.length) {
+            throw new EmptyResultError('rest-countries country', `No countries matched "${name}".`);
+        }
+        // Sort by population descending so the most "expected" hit is first.
+        const sorted = [...list].sort((a, b) => (b?.population ?? 0) - (a?.population ?? 0));
+        return sorted.slice(0, limit).map((c, i) => ({ rank: i + 1, ...projectCountry(c) }));
+    },
+});

package/clis/rest-countries/region.js

@@ -0,0 +1,64 @@
+// rest-countries region — list every country in a region.
+//
+// Region values: africa / americas / asia / europe / oceania / antarctic.
+// Subregions ("eastern asia") are not supported by this command — they go
+// through the v3.1 `subregion/` endpoint which behaves identically.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    COUNTRY_FIELDS,
+    REST_COUNTRIES_BASE,
+    projectCountry,
+    requireBoundedInt,
+    requireRegion,
+    restCountriesFetch,
+} from './utils.js';
+
+cli({
+    site: 'rest-countries',
+    name: 'region',
+    access: 'read',
+    description: 'List countries in a region (africa / americas / asia / europe / oceania / antarctic)',
+    domain: 'restcountries.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'region', positional: true, required: true, help: 'Region name (case-insensitive)' },
+        { name: 'limit', type: 'int', default: 250, help: 'Max rows (1-250)' },
+    ],
+    columns: [
+        'rank',
+        'commonName',
+        'officialName',
+        'cca2',
+        'cca3',
+        'ccn3',
+        'capital',
+        'region',
+        'subregion',
+        'population',
+        'area',
+        'languages',
+        'currencies',
+        'latitude',
+        'longitude',
+        'timezones',
+        'independent',
+        'unMember',
+        'landlocked',
+        'flag',
+        'url',
+    ],
+    func: async (args) => {
+        const region = requireRegion(args.region);
+        const limit = requireBoundedInt(args.limit, 250, 250);
+        const url = `${REST_COUNTRIES_BASE}/region/${encodeURIComponent(region)}?fields=${COUNTRY_FIELDS}`;
+        const body = await restCountriesFetch(url, 'rest-countries region');
+        const list = Array.isArray(body) ? body : [];
+        if (!list.length) {
+            throw new EmptyResultError('rest-countries region', `No countries returned for region "${region}".`);
+        }
+        const sorted = [...list].sort((a, b) => (b?.population ?? 0) - (a?.population ?? 0));
+        return sorted.slice(0, limit).map((c, i) => ({ rank: i + 1, ...projectCountry(c) }));
+    },
+});

package/clis/rest-countries/rest-countries.test.js

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './country.js';
+import './region.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('rest-countries country adapter', () => {
+    const cmd = getRegistry().get('rest-countries/country');
+
+    it('rejects bad args before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ name: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ name: 'japan', limit: 9999 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('throttled', { status: 429 })));
+        await expect(cmd.func({ name: 'japan' })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('maps HTTP 404 to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('not found', { status: 404 })));
+        await expect(cmd.func({ name: 'no-country-by-this-name' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('round-trips cca3 from row into restcountries.com alpha URL', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify([
+            {
+                name: { common: 'Japan', official: 'Japan' },
+                cca2: 'JP', cca3: 'JPN', ccn3: '392',
+                capital: ['Tokyo'],
+                region: 'Asia', subregion: 'Eastern Asia',
+                population: 125000000, area: 377000,
+                languages: { jpn: 'Japanese' },
+                currencies: { JPY: { name: 'Japanese yen', symbol: '¥' } },
+                latlng: [36, 138], timezones: ['UTC+09:00'], independent: true, unMember: true, landlocked: false, flag: '🇯🇵',
+            },
+        ]), { status: 200 })));
+        const rows = await cmd.func({ name: 'japan', limit: 5 });
+        expect(rows[0]).toMatchObject({
+            rank: 1, commonName: 'Japan', cca2: 'JP', cca3: 'JPN',
+            capital: 'Tokyo', region: 'Asia',
+            languages: 'Japanese', currencies: 'JPY (Japanese yen)',
+            latitude: 36, longitude: 138,
+            url: 'https://restcountries.com/v3.1/alpha/jpn',
+        });
+    });
+});
+
+describe('rest-countries region adapter', () => {
+    const cmd = getRegistry().get('rest-countries/region');
+
+    it('rejects unknown regions before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ region: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ region: 'middle-earth' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('throws EmptyResultError on empty payload', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify([]), { status: 200 })));
+        await expect(cmd.func({ region: 'oceania' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('sorts by population descending so largest country is rank 1', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify([
+            { name: { common: 'Tuvalu' }, cca3: 'TUV', population: 12000 },
+            { name: { common: 'Australia' }, cca3: 'AUS', population: 26000000 },
+            { name: { common: 'Fiji' }, cca3: 'FJI', population: 900000 },
+        ]), { status: 200 })));
+        const rows = await cmd.func({ region: 'oceania' });
+        expect(rows.map((r) => r.commonName)).toEqual(['Australia', 'Fiji', 'Tuvalu']);
+        expect(rows[0]).toMatchObject({ cca3: 'AUS', url: 'https://restcountries.com/v3.1/alpha/aus' });
+    });
+});

package/clis/rest-countries/utils.js

@@ -0,0 +1,126 @@
+// Shared helpers for the REST Countries adapter (https://restcountries.com).
+//
+// REST Countries is a free public country-metadata API, no API key required.
+// We hit v3.1 only. The `fields=` query param is mandatory in v3.1 to keep
+// payloads small; we always specify the agent-useful projection.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const REST_COUNTRIES_BASE = 'https://restcountries.com/v3.1';
+const UA = 'opencli-rest-countries-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';
+
+// REST Countries valid region values; subregions are validated server-side.
+export const REST_COUNTRIES_REGIONS = new Set(['africa', 'americas', 'asia', 'europe', 'oceania', 'antarctic']);
+
+// Fields the adapter always requests; keep this list aligned with `columns` so
+// rows never have null-where-absent silent drops.
+export const COUNTRY_FIELDS = [
+    'name', 'cca2', 'cca3', 'ccn3', 'capital', 'region', 'subregion',
+    'population', 'area', 'languages', 'currencies', 'flag', 'latlng', 'timezones',
+    'independent', 'unMember', 'landlocked',
+].join(',');
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`rest-countries ${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(`rest-countries ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`rest-countries ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireRegion(value) {
+    const raw = String(value ?? '').trim().toLowerCase();
+    if (!raw) throw new ArgumentError('rest-countries region is required (e.g. "europe", "asia")');
+    if (!REST_COUNTRIES_REGIONS.has(raw)) {
+        throw new ArgumentError(
+            `rest-countries region "${value}" is not recognised`,
+            `Allowed regions: ${[...REST_COUNTRIES_REGIONS].join(', ')}.`,
+        );
+    }
+    return raw;
+}
+
+export async function restCountriesFetch(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 restcountries.com is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `REST Countries 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;
+}
+
+/** Convert REST Countries' `{cur: {name, symbol}}` map to a comma-joined list. */
+export function joinCurrencies(currencies) {
+    if (!currencies || typeof currencies !== 'object') return '';
+    return Object.entries(currencies)
+        .map(([code, info]) => {
+            const name = info && typeof info.name === 'string' ? info.name : '';
+            return name ? `${code} (${name})` : code;
+        })
+        .join(', ');
+}
+
+/** Convert `{eng: 'English', fra: 'French'}` map to a comma-joined list of language names. */
+export function joinLanguages(languages) {
+    if (!languages || typeof languages !== 'object') return '';
+    return Object.values(languages).filter((v) => typeof v === 'string' && v.trim()).join(', ');
+}
+
+/** Project a REST Countries v3.1 country object into a row matching the adapter columns. */
+export function projectCountry(c) {
+    const common = c?.name?.common ?? null;
+    const official = c?.name?.official ?? null;
+    const cca3 = typeof c?.cca3 === 'string' ? c.cca3 : null;
+    return {
+        commonName: typeof common === 'string' ? common : null,
+        officialName: typeof official === 'string' ? official : null,
+        cca2: typeof c?.cca2 === 'string' ? c.cca2 : null,
+        cca3,
+        ccn3: typeof c?.ccn3 === 'string' ? c.ccn3 : null,
+        capital: Array.isArray(c?.capital) ? c.capital.join(', ') : null,
+        region: typeof c?.region === 'string' ? c.region : null,
+        subregion: typeof c?.subregion === 'string' ? c.subregion : null,
+        population: typeof c?.population === 'number' ? c.population : null,
+        area: typeof c?.area === 'number' ? c.area : null,
+        languages: joinLanguages(c?.languages),
+        currencies: joinCurrencies(c?.currencies),
+        latitude: Array.isArray(c?.latlng) && typeof c.latlng[0] === 'number' ? c.latlng[0] : null,
+        longitude: Array.isArray(c?.latlng) && typeof c.latlng[1] === 'number' ? c.latlng[1] : null,
+        timezones: Array.isArray(c?.timezones) ? c.timezones.join(', ') : null,
+        independent: typeof c?.independent === 'boolean' ? c.independent : null,
+        unMember: typeof c?.unMember === 'boolean' ? c.unMember : null,
+        landlocked: typeof c?.landlocked === 'boolean' ? c.landlocked : null,
+        flag: typeof c?.flag === 'string' ? c.flag : null,
+        url: cca3 ? `https://restcountries.com/v3.1/alpha/${cca3.toLowerCase()}` : '',
+    };
+}

package/clis/reuters/article-detail.js

@@ -0,0 +1,53 @@
+/**
+ * Reuters article-detail — full article body + canonical metadata.
+ *
+ * Pairs with `reuters search` (use the `url` column to round-trip into
+ * detail). Reads the in-page Fusion globalContent payload + paragraph DOM.
+ */
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { buildArticleDetailScript, mapArticleDetail } from './utils.js';
+
+const REUTERS_HOST = /^https?:\/\/(?:www\.)?reuters\.com\//i;
+
+cli({
+    site: 'reuters',
+    name: 'article-detail',
+    access: 'read',
+    description: 'Reuters 路透社文章详情：标题/作者/正文文本',
+    domain: 'www.reuters.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'url', required: true, positional: true, help: 'Reuters article URL (must be on reuters.com)' },
+    ],
+    columns: ['title', 'date', 'section', 'section_path', 'authors', 'description', 'word_count', 'url', 'body'],
+    func: async (page, kwargs) => {
+        const url = String(kwargs.url || '').trim();
+        if (!url) {
+            throw new ArgumentError('Article URL cannot be empty');
+        }
+        if (!REUTERS_HOST.test(url)) {
+            throw new ArgumentError(`URL must be on reuters.com, got ${url}`);
+        }
+        await page.goto(url);
+        await page.wait(2);
+        const result = await page.evaluate(buildArticleDetailScript());
+        if (result?.error) {
+            throw new CommandExecutionError(`Reuters article-detail failed inside the page: ${result.error}`);
+        }
+        if (result?.authRequired) {
+            throw new AuthRequiredError('www.reuters.com', 'Reuters article-detail is gated by login, subscription, or human verification');
+        }
+        if (!result || result.ok !== true) {
+            throw new CommandExecutionError(
+                'Reuters article-detail returned no payload',
+                'Check that the URL points to a Reuters article and that the page loaded',
+            );
+        }
+        const detail = mapArticleDetail(result.body?.article, result.body?.bodyText, url);
+        if (!detail || (!detail.title && !detail.body)) {
+            throw new EmptyResultError('reuters article-detail', 'Page rendered no article body — likely paywalled or a non-article URL');
+        }
+        return [detail];
+    },
+});