@jackwener/opencli 1.7.11 → 1.7.13

package/clis/ctrip/ctrip.test.js

@@ -0,0 +1,234 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './search.js';
+import './hotel-suggest.js';
+import { buildUrl, mapSuggestRow, parseLimit, pickCoords } from './utils.js';
+
+function ok(payload) {
+    return new Response(JSON.stringify(payload), { status: 200 });
+}
+
+const SHANGHAI_CITY = {
+    id: '2', type: 'City', word: '上海', cityId: 2, cityName: '上海',
+    provinceName: '上海', countryName: '中国', cityEName: 'Shanghai',
+    countryEName: 'China', displayName: '上海, 中国', displayType: '城市',
+    eName: 'Shanghai', commentScore: 0,
+    lat: 0, lon: 0, gLat: 0, gLon: 0, gdLat: 31.2304, gdLon: 121.4737,
+};
+
+const FORBIDDEN_CITY = {
+    id: '4189051', type: 'Markland', word: '故宫博物院', cityId: 1, cityName: '北京',
+    provinceName: '北京', countryName: '中国', displayName: '故宫博物院, 北京, 中国',
+    displayType: '地标', eName: 'The Palace Museum', commentScore: 4.8, cStar: 0,
+    lat: 0, lon: 0, gLat: 0, gLon: 0, gdLat: 39.9177, gdLon: 116.397,
+};
+
+const HANOI_LANDMARK = {
+    id: '6790582', type: 'Markland', word: '升龙皇城', cityId: 286, cityName: '河内',
+    provinceName: '', countryName: '越南', displayName: '升龙皇城, 河内, 越南',
+    displayType: '地标', eName: 'Imperial Citadel of Thang Long', commentScore: 0,
+    lat: 0, lon: 0, gLat: 21.0352, gLon: 105.8403, gdLat: 0, gdLon: 0,
+};
+
+const HOTEL_ROW = {
+    id: '133133582', type: 'Hotel', word: '汉庭酒店上海陆家嘴店', cityId: 2,
+    cityName: '上海', provinceName: '上海', countryName: '中国',
+    displayName: '汉庭酒店上海陆家嘴店, 上海, 中国', displayType: '酒店',
+    cStar: 4.2, commentScore: 0,
+};
+
+describe('ctrip parseLimit', () => {
+    it('returns fallback for undefined / null / empty', () => {
+        expect(parseLimit(undefined)).toBe(15);
+        expect(parseLimit(null)).toBe(15);
+        expect(parseLimit('')).toBe(15);
+    });
+    it('accepts integers in [1, 50]', () => {
+        expect(parseLimit(1)).toBe(1);
+        expect(parseLimit(50)).toBe(50);
+        expect(parseLimit('25')).toBe(25);
+    });
+    it('rejects non-integer', () => {
+        expect(() => parseLimit('abc')).toThrow('--limit must be an integer');
+        expect(() => parseLimit(3.5)).toThrow('--limit must be an integer');
+    });
+    it('rejects out-of-range without silent clamp', () => {
+        expect(() => parseLimit(0)).toThrow('--limit must be between 1 and 50, got 0');
+        expect(() => parseLimit(51)).toThrow('--limit must be between 1 and 50, got 51');
+        expect(() => parseLimit(-3)).toThrow('--limit must be between 1 and 50');
+    });
+});
+
+describe('ctrip pickCoords', () => {
+    it('prefers gd coords (mainland) when present', () => {
+        expect(pickCoords(SHANGHAI_CITY)).toEqual({ lat: 31.2304, lon: 121.4737 });
+    });
+    it('falls back to g coords (international) when gd is zero', () => {
+        expect(pickCoords(HANOI_LANDMARK)).toEqual({ lat: 21.0352, lon: 105.8403 });
+    });
+    it('returns null/null when all coord variants are zero', () => {
+        expect(pickCoords(HOTEL_ROW)).toEqual({ lat: null, lon: null });
+    });
+});
+
+describe('ctrip buildUrl', () => {
+    it('constructs city URL', () => {
+        expect(buildUrl(SHANGHAI_CITY)).toBe('https://you.ctrip.com/place/%E4%B8%8A%E6%B5%B72.html');
+    });
+    it('constructs landmark URL', () => {
+        expect(buildUrl(FORBIDDEN_CITY)).toBe('https://you.ctrip.com/sight/%E5%8C%97%E4%BA%AC1/4189051.html');
+    });
+    it('constructs hotel URL', () => {
+        expect(buildUrl(HOTEL_ROW)).toBe('https://hotels.ctrip.com/hotels/detail/?hotelid=133133582');
+    });
+    it('returns null for unknown type rather than fabricating', () => {
+        expect(buildUrl({ type: 'WhoKnows', id: '1', cityId: 1, cityName: 'X' })).toBeNull();
+    });
+});
+
+describe('ctrip mapSuggestRow', () => {
+    it('preserves all geo / english / id columns (no silent column drop)', () => {
+        const row = mapSuggestRow(FORBIDDEN_CITY, 0);
+        expect(row).toEqual({
+            rank: 1,
+            id: '4189051',
+            type: 'Markland',
+            displayType: '地标',
+            name: '故宫博物院, 北京, 中国',
+            eName: 'The Palace Museum',
+            cityId: 1,
+            cityName: '北京',
+            provinceName: '北京',
+            countryName: '中国',
+            lat: 39.9177,
+            lon: 116.397,
+            score: 4.8,
+            url: 'https://you.ctrip.com/sight/%E5%8C%97%E4%BA%AC1/4189051.html',
+        });
+    });
+    it('uses cStar as score fallback when commentScore is 0', () => {
+        const row = mapSuggestRow({ ...FORBIDDEN_CITY, commentScore: 0, cStar: 4.5 }, 2);
+        expect(row.score).toBe(4.5);
+    });
+    it('returns null score when both commentScore and cStar are missing/zero', () => {
+        expect(mapSuggestRow(SHANGHAI_CITY, 0).score).toBeNull();
+    });
+});
+
+describe('ctrip search command (registry-level)', () => {
+    const cmd = getRegistry().get('ctrip/search');
+    beforeEach(() => vi.unstubAllGlobals());
+
+    it('declares Strategy.PUBLIC + browser:false + access:read', () => {
+        expect(cmd.access).toBe('read');
+        expect(cmd.browser).toBe(false);
+        expect(String(cmd.strategy)).toContain('public');
+    });
+
+    it('maps live response with full column shape', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(ok({
+            Result: true, ErrorCode: 0,
+            Response: { searchResults: [SHANGHAI_CITY, FORBIDDEN_CITY] },
+        }))));
+        const rows = await cmd.func({ query: '上海', limit: 5 });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].cityId).toBe(2);
+        expect(rows[0].lat).toBeCloseTo(31.2304);
+        expect(rows[1].url).toContain('/sight/');
+        // shape parity: every row has every declared column key
+        for (const row of rows) {
+            for (const col of cmd.columns) expect(row).toHaveProperty(col);
+        }
+    });
+
+    it('rejects empty query with ArgumentError', async () => {
+        await expect(cmd.func({ query: '   ', limit: 3 })).rejects.toThrow('Search keyword cannot be empty');
+    });
+
+    it('surfaces fetch failures as typed FETCH_ERROR', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(new Response('{}', { status: 503 }))));
+        await expect(cmd.func({ query: '上海', limit: 3 })).rejects.toMatchObject({
+            code: 'FETCH_ERROR',
+        });
+    });
+
+    it('wraps network failures as typed FETCH_ERROR', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.reject(new Error('socket hang up'))));
+        await expect(cmd.func({ query: '上海', limit: 3 })).rejects.toMatchObject({
+            code: 'FETCH_ERROR',
+            message: expect.stringContaining('socket hang up'),
+        });
+    });
+
+    it('wraps invalid JSON as typed COMMAND_EXEC', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(new Response('not json', { status: 200 }))));
+        await expect(cmd.func({ query: '上海', limit: 3 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('invalid JSON'),
+        });
+    });
+
+    it('surfaces in-band Result=false as typed COMMAND_EXEC', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(ok({
+            Result: false, ErrorCode: 17,
+        }))));
+        await expect(cmd.func({ query: '上海', limit: 3 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('surfaces empty results as EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(ok({
+            Result: true, ErrorCode: 0, Response: { searchResults: [] },
+        }))));
+        await expect(cmd.func({ query: '上海', limit: 3 })).rejects.toThrow('ctrip search returned no data');
+    });
+
+    it('rejects --limit 0 / 51 with ArgumentError (no silent clamp)', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(ok({
+            Result: true, ErrorCode: 0, Response: { searchResults: [SHANGHAI_CITY] },
+        }))));
+        await expect(cmd.func({ query: '上海', limit: 0 })).rejects.toThrow('--limit');
+        await expect(cmd.func({ query: '上海', limit: 51 })).rejects.toThrow('--limit');
+    });
+});
+
+describe('ctrip hotel-suggest command (registry-level)', () => {
+    const cmd = getRegistry().get('ctrip/hotel-suggest');
+    beforeEach(() => vi.unstubAllGlobals());
+
+    it('declares Strategy.PUBLIC + browser:false + access:read', () => {
+        expect(cmd.access).toBe('read');
+        expect(cmd.browser).toBe(false);
+        expect(String(cmd.strategy)).toContain('public');
+    });
+
+    it('maps Hotel rows with hotel detail URL', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(ok({
+            Result: true, ErrorCode: 0,
+            Response: { searchResults: [SHANGHAI_CITY, HOTEL_ROW] },
+        }))));
+        const rows = await cmd.func({ query: '汉庭', limit: 5 });
+        expect(rows).toHaveLength(2);
+        const hotel = rows.find((r) => r.type === 'Hotel');
+        expect(hotel.url).toBe('https://hotels.ctrip.com/hotels/detail/?hotelid=133133582');
+    });
+
+    it('passes searchType=H to the upstream endpoint', async () => {
+        const fetchMock = vi.fn(() => Promise.resolve(ok({
+            Result: true, ErrorCode: 0,
+            Response: { searchResults: [HOTEL_ROW] },
+        })));
+        vi.stubGlobal('fetch', fetchMock);
+        await cmd.func({ query: '汉庭', limit: 5 });
+        const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+        expect(body.searchType).toBe('H');
+    });
+
+    it('surfaces empty hotel-context lookup as EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(ok({
+            Result: true, ErrorCode: 0, Response: { searchResults: [] },
+        }))));
+        await expect(cmd.func({ query: 'zzz', limit: 5 })).rejects.toThrow('ctrip hotel-suggest returned no data');
+    });
+});

package/clis/ctrip/hotel-suggest.js

@@ -0,0 +1,45 @@
+/**
+ * 携程酒店 hotel-context suggest — public city/business-area/hotel lookup.
+ *
+ * Distinct from `ctrip/search` (destination): the same backing endpoint is
+ * called with `searchType=H`, surfacing Hotel and BusinessArea rows that the
+ * destination flavour does not return.
+ */
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchSuggest, mapSuggestRow, parseLimit } from './utils.js';
+
+cli({
+    site: 'ctrip',
+    name: 'hotel-suggest',
+    access: 'read',
+    description: '搜索携程酒店上下文联想：城市、商圈、单酒店匹配',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', required: true, positional: true, help: 'Search keyword (city, business area, or hotel name)' },
+        { name: 'limit', type: 'int', default: 15, help: 'Number of results (1-50)' },
+    ],
+    columns: [
+        'rank', 'id', 'type', 'displayType', 'name', 'eName',
+        'cityId', 'cityName', 'provinceName', 'countryName',
+        'lat', 'lon', 'score', 'url',
+    ],
+    func: async (kwargs) => {
+        const query = String(kwargs.query || '').trim();
+        if (!query) {
+            throw new ArgumentError('Search keyword cannot be empty');
+        }
+        const limit = parseLimit(kwargs.limit);
+        const raw = await fetchSuggest(query, 'H');
+        const rows = raw
+            .filter((item) => !!item && typeof item === 'object')
+            .slice(0, limit)
+            .map(mapSuggestRow)
+            .filter((row) => row.name);
+        if (!rows.length) {
+            throw new EmptyResultError('ctrip hotel-suggest', 'Try a city, business area, or hotel keyword such as "陆家嘴" or "汉庭酒店"');
+        }
+        return rows;
+    },
+});

package/clis/ctrip/search.js

@@ -1,86 +1,41 @@
 /**
- * 携程旅行搜索 — public destination and hotel suggestion lookup.
+ * 携程旅行 destination suggest — public city/landmark/scenic-spot lookup.
  */
-import { ArgumentError, CliError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
-function clampLimit(raw, fallback = 15) {
-    const parsed = Number(raw);
-    if (!Number.isFinite(parsed))
-        return fallback;
-    return Math.max(1, Math.min(Math.floor(parsed), 50));
-}
-function mapSearchResults(results, limit) {
-    return results
-        .filter((item) => !!item && typeof item === 'object')
-        .slice(0, limit)
-        .map((item, index) => ({
-        rank: index + 1,
-        name: String(item.displayName || item.word || item.cityName || '').replace(/\s+/g, ' ').trim(),
-        type: String(item.displayType || item.type || '').replace(/\s+/g, ' ').trim(),
-        score: item.commentScore ?? item.cStar ?? '',
-        price: item.price ?? item.minPrice ?? '',
-        url: '',
-    }))
-        .filter((item) => item.name);
-}
+import { fetchSuggest, mapSuggestRow, parseLimit } from './utils.js';
+
 cli({
     site: 'ctrip',
     name: 'search',
-    description: '搜索携程目的地、景区和酒店联想结果',
+    access: 'read',
+    description: '搜索携程目的地、景区、火车站和地标联想结果',
     strategy: Strategy.PUBLIC,
     browser: false,
     args: [
-        { name: 'query', required: true, positional: true, help: 'Search keyword (city or attraction)' },
-        { name: 'limit', type: 'int', default: 15, help: 'Number of results' },
+        { name: 'query', required: true, positional: true, help: 'Search keyword (city, scenic spot, landmark)' },
+        { name: 'limit', type: 'int', default: 15, help: 'Number of results (1-50)' },
+    ],
+    columns: [
+        'rank', 'id', 'type', 'displayType', 'name', 'eName',
+        'cityId', 'cityName', 'provinceName', 'countryName',
+        'lat', 'lon', 'score', 'url',
     ],
-    columns: ['rank', 'name', 'type', 'score', 'price', 'url'],
     func: async (kwargs) => {
         const query = String(kwargs.query || '').trim();
         if (!query) {
             throw new ArgumentError('Search keyword cannot be empty');
         }
-        const limit = clampLimit(kwargs.limit);
-        const response = await fetch('https://m.ctrip.com/restapi/soa2/21881/json/gaHotelSearchEngine', {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                keyword: query,
-                searchType: 'D',
-                platform: 'online',
-                pageID: '102001',
-                head: {
-                    Locale: 'zh-CN',
-                    LocaleController: 'zh_cn',
-                    Currency: 'CNY',
-                    PageId: '102001',
-                    clientID: 'opencli-ctrip-search',
-                    group: 'ctrip',
-                    Frontend: {
-                        sessionID: 1,
-                        pvid: 1,
-                    },
-                    HotelExtension: {
-                        group: 'CTRIP',
-                        WebpSupport: false,
-                    },
-                },
-            }),
-        });
-        if (!response.ok) {
-            throw new CliError('FETCH_ERROR', `ctrip search failed with status ${response.status}`, 'Retry the command or verify ctrip.com is reachable');
-        }
-        const payload = await response.json();
-        const rawResults = Array.isArray(payload?.Response?.searchResults) ? payload.Response.searchResults : [];
-        const results = mapSearchResults(rawResults, limit);
-        if (!results.length) {
-            throw new EmptyResultError('ctrip search', 'Try a destination, scenic spot, or hotel keyword such as "苏州" or "朱家尖"');
+        const limit = parseLimit(kwargs.limit);
+        const raw = await fetchSuggest(query, 'D');
+        const rows = raw
+            .filter((item) => !!item && typeof item === 'object')
+            .slice(0, limit)
+            .map(mapSuggestRow)
+            .filter((row) => row.name);
+        if (!rows.length) {
+            throw new EmptyResultError('ctrip search', 'Try a destination, scenic spot, or landmark keyword such as "苏州" or "故宫"');
         }
-        return results;
+        return rows;
     },
 });
-export const __test__ = {
-    clampLimit,
-    mapSearchResults,
-};

package/clis/ctrip/utils.js

@@ -0,0 +1,175 @@
+/**
+ * Shared helpers for ctrip public destination/hotel suggestion endpoints.
+ *
+ * The single backing endpoint `https://m.ctrip.com/restapi/soa2/21881/json/gaHotelSearchEngine`
+ * accepts a `searchType` discriminator:
+ *   - `D` → destination suggest (cities, scenic spots, railway stations, landmarks)
+ *   - `H` → hotel-context suggest (cities, business areas, individual hotels)
+ *
+ * Response shape is identical; we surface every field the endpoint emits as a
+ * stable column so callers do not silently lose geo / English / id metadata.
+ */
+import { ArgumentError, CliError } from '@jackwener/opencli/errors';
+
+const ENDPOINT = 'https://m.ctrip.com/restapi/soa2/21881/json/gaHotelSearchEngine';
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 50;
+
+export function parseLimit(raw, fallback = 15) {
+    if (raw === undefined || raw === null || raw === '') return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+        throw new ArgumentError(`--limit must be an integer between ${MIN_LIMIT} and ${MAX_LIMIT}, got ${JSON.stringify(raw)}`);
+    }
+    if (parsed < MIN_LIMIT || parsed > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be between ${MIN_LIMIT} and ${MAX_LIMIT}, got ${parsed}`);
+    }
+    return parsed;
+}
+
+export async function fetchSuggest(query, searchType) {
+    let response;
+    try {
+        response = await fetch(ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                keyword: query,
+                searchType,
+                platform: 'online',
+                pageID: '102001',
+                head: {
+                    Locale: 'zh-CN',
+                    LocaleController: 'zh_cn',
+                    Currency: 'CNY',
+                    PageId: '102001',
+                    clientID: 'opencli-ctrip',
+                    group: 'ctrip',
+                    Frontend: { sessionID: 1, pvid: 1 },
+                    HotelExtension: { group: 'CTRIP', WebpSupport: false },
+                },
+            }),
+        });
+    } catch (err) {
+        throw new CliError(
+            'FETCH_ERROR',
+            `ctrip suggest fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+            'Check your network connection and retry',
+        );
+    }
+    if (!response.ok) {
+        throw new CliError(
+            'FETCH_ERROR',
+            `ctrip suggest failed with status ${response.status}`,
+            'Retry the command or verify ctrip.com is reachable',
+        );
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    } catch (err) {
+        throw new CliError(
+            'COMMAND_EXEC',
+            `ctrip suggest returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+            'Ctrip may have changed the endpoint response format; retry later',
+        );
+    }
+    if (payload && payload.Result === false) {
+        const code = payload.ErrorCode ?? 'unknown';
+        throw new CliError(
+            'COMMAND_EXEC',
+            `ctrip suggest API returned Result=false (ErrorCode=${code})`,
+            'Verify keyword and retry; this typically means upstream rejected the query envelope',
+        );
+    }
+    return Array.isArray(payload?.Response?.searchResults) ? payload.Response.searchResults : [];
+}
+
+/**
+ * Pick the best lat/lon pair available.
+ *
+ * Domestic Mainland China rows ship `gdLat`/`gdLon` (gaode); international rows
+ * ship `gLat`/`gLon` (google/wgs84). `lat`/`lon` is the legacy flat field — fall
+ * through to it last. Zero values are treated as "missing" since the endpoint
+ * uses 0.0 as a sentinel for unknown coords.
+ */
+export function pickCoords(item) {
+    const candidates = [
+        [item.gdLat, item.gdLon],
+        [item.gLat, item.gLon],
+        [item.lat, item.lon],
+    ];
+    for (const [la, lo] of candidates) {
+        if (Number.isFinite(la) && Number.isFinite(lo) && (la !== 0 || lo !== 0)) {
+            return { lat: la, lon: lo };
+        }
+    }
+    return { lat: null, lon: null };
+}
+
+/**
+ * Build a canonical user-facing URL from the suggest item type + ids.
+ * Unknown types return null (do not silently fabricate URLs).
+ */
+export function buildUrl(item) {
+    const id = item?.id ? String(item.id) : '';
+    const cityId = item?.cityId ?? '';
+    const cityName = item?.cityName ? String(item.cityName) : '';
+    switch (item?.type) {
+        case 'City':
+            return cityId ? `https://you.ctrip.com/place/${encodeURIComponent(cityName)}${cityId}.html` : null;
+        case 'Markland':
+            return id && cityId
+                ? `https://you.ctrip.com/sight/${encodeURIComponent(cityName)}${cityId}/${id}.html`
+                : null;
+        case 'Hotel':
+            return id ? `https://hotels.ctrip.com/hotels/detail/?hotelid=${id}` : null;
+        case 'BusinessArea':
+        case 'Zone':
+            return cityId && id
+                ? `https://hotels.ctrip.com/hotels/list?city=${cityId}&zone=${id}`
+                : null;
+        case 'RailwayStation':
+            return id ? `https://trains.ctrip.com/trainstation/${id}.html` : null;
+        default:
+            return null;
+    }
+}
+
+function nz(v) {
+    return Number.isFinite(v) && v !== 0 ? v : null;
+}
+
+function firstNonZero(...values) {
+    for (const v of values) {
+        const n = Number(v);
+        if (Number.isFinite(n) && n !== 0) return n;
+    }
+    return null;
+}
+
+/**
+ * Project a raw suggest row into the stable adapter column shape.
+ * No silent fallbacks: every column has a deterministic value (string|number|null).
+ */
+export function mapSuggestRow(item, index) {
+    const { lat, lon } = pickCoords(item);
+    return {
+        rank: index + 1,
+        id: item?.id ? String(item.id) : null,
+        type: item?.type ? String(item.type) : null,
+        displayType: item?.displayType ? String(item.displayType).trim() : null,
+        name: String(item?.displayName || item?.word || item?.cityName || '').replace(/\s+/g, ' ').trim() || null,
+        eName: item?.eName ? String(item.eName).trim() : null,
+        cityId: Number.isFinite(item?.cityId) && item.cityId !== 0 ? item.cityId : null,
+        cityName: item?.cityName ? String(item.cityName).trim() : null,
+        provinceName: item?.provinceName ? String(item.provinceName).trim() : null,
+        countryName: item?.countryName ? String(item.countryName).trim() : null,
+        lat,
+        lon,
+        score: firstNonZero(item?.commentScore, item?.cStar),
+        url: buildUrl(item),
+    };
+}
+
+export const __test__ = { ENDPOINT, MIN_LIMIT, MAX_LIMIT };

package/clis/cursor/ask.js

@@ -1,20 +1,24 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { selectorError } from '@jackwener/opencli/errors';
+import { ArgumentError, selectorError } from '@jackwener/opencli/errors';
 export const askCommand = cli({
     site: 'cursor',
     name: 'ask',
+    access: 'write',
     description: 'Send a prompt and wait for the AI response (send + wait + read)',
     domain: 'localhost',
     strategy: Strategy.UI,
     browser: true,
     args: [
         { name: 'text', required: true, positional: true, help: 'Prompt to send' },
-        { name: 'timeout', required: false, help: 'Max seconds to wait for response (default: 30)', default: '30' },
+        { name: 'timeout', type: 'int', required: false, help: 'Max seconds to wait for response (default: 30)', default: 30 },
     ],
     columns: ['Role', 'Text'],
     func: async (page, kwargs) => {
         const text = kwargs.text;
-        const timeout = parseInt(kwargs.timeout, 10) || 30;
+        const timeout = kwargs.timeout;
+        if (!Number.isInteger(timeout) || timeout < 1) {
+            throw new ArgumentError('--timeout must be a positive integer (seconds)');
+        }
         // Count existing messages before sending
         const beforeCount = await page.evaluate(`
       document.querySelectorAll('[data-message-role]').length

package/clis/cursor/composer.js

@@ -3,6 +3,7 @@ import { selectorError } from '@jackwener/opencli/errors';
 export const composerCommand = cli({
     site: 'cursor',
     name: 'composer',
+    access: 'write',
     description: 'Send a prompt directly into Cursor Composer (Cmd+I shortcut)',
     domain: 'localhost',
     strategy: Strategy.UI,

package/clis/cursor/export.js

@@ -4,6 +4,7 @@ function makeExportCommand(site, readSelector) {
     return cli({
         site,
         name: 'export',
+    access: 'read',
         description: `Export the current ${site} conversation to a Markdown file`,
         domain: 'localhost',
         strategy: Strategy.UI,

package/clis/cursor/extract-code.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 export const extractCodeCommand = cli({
     site: 'cursor',
     name: 'extract-code',
+    access: 'read',
     description: 'Extract multi-line code blocks from the current Cursor conversation',
     domain: 'localhost',
     strategy: Strategy.UI,

package/clis/cursor/history.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 export const historyCommand = cli({
     site: 'cursor',
     name: 'history',
+    access: 'read',
     description: 'List recent chat sessions from the Cursor sidebar',
     domain: 'localhost',
     strategy: Strategy.UI,

package/clis/cursor/model.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 export const modelCommand = cli({
     site: 'cursor',
     name: 'model',
+    access: 'read',
     description: 'Get or switch the currently active AI model in Cursor',
     domain: 'localhost',
     strategy: Strategy.UI,

package/clis/cursor/read.js

@@ -3,6 +3,7 @@ import { EmptyResultError } from '@jackwener/opencli/errors';
 export const readCommand = cli({
     site: 'cursor',
     name: 'read',
+    access: 'read',
     description: 'Read the current Cursor chat/composer conversation history',
     domain: 'localhost',
     strategy: Strategy.UI,

package/clis/cursor/send.js

@@ -3,6 +3,7 @@ import { selectorError } from '@jackwener/opencli/errors';
 export const sendCommand = cli({
     site: 'cursor',
     name: 'send',
+    access: 'write',
     description: 'Send a prompt directly into Cursor Composer/Chat',
     domain: 'localhost',
     strategy: Strategy.UI,