@jackwener/opencli 1.7.12 → 1.7.13

package/clis/lichess/lichess.test.js

@@ -0,0 +1,85 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './user.js';
+import './top.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('lichess user adapter', () => {
+    const cmd = getRegistry().get('lichess/user');
+
+    it('rejects bad usernames before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ username: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ username: 'a' })).rejects.toThrow(ArgumentError); // too short
+        await expect(cmd.func({ username: 'has space' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('rate limited', { status: 429 })));
+        await expect(cmd.func({ username: 'somebody' })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('treats disabled accounts as EmptyResultError (not row of nulls)', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            id: 'closed-user', username: 'ClosedUser', disabled: true,
+        }), { status: 200 })));
+        await expect(cmd.func({ username: 'ClosedUser' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('picks the most-played perf as topPerf', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            id: 'someplayer',
+            username: 'SomePlayer',
+            createdAt: 1543000000000,
+            seenAt: 1700000000000,
+            count: { all: 100, win: 50, loss: 30, draw: 20 },
+            perfs: {
+                bullet: { games: 9000, rating: 2700 },
+                blitz: { games: 100, rating: 2200 },
+                puzzle: { games: 99999, rating: 2900 }, // ignored — not playable
+            },
+        }), { status: 200 })));
+        const rows = await cmd.func({ username: 'SomePlayer' });
+        expect(rows[0]).toMatchObject({
+            username: 'SomePlayer', id: 'someplayer',
+            gamesAll: 100, topPerfName: 'bullet', topPerfRating: 2700, topPerfGames: 9000,
+            url: 'https://lichess.org/@/SomePlayer',
+        });
+    });
+});
+
+describe('lichess top adapter', () => {
+    const cmd = getRegistry().get('lichess/top');
+
+    it('rejects unknown perf types before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ perf: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ perf: 'turbo' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ perf: 'blitz', limit: 9999 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('throws EmptyResultError on empty leaderboard', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({ users: [] }), { status: 200 })));
+        await expect(cmd.func({ perf: 'blitz', limit: 5 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('round-trips username from leaderboard into perf-specific URL', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            users: [{ id: 'magnus', username: 'Magnus', title: 'GM', perfs: { blitz: { rating: 3001, progress: 7 } } }],
+        }), { status: 200 })));
+        const rows = await cmd.func({ perf: 'blitz', limit: 3 });
+        expect(rows[0]).toMatchObject({
+            rank: 1, username: 'Magnus', title: 'GM', rating: 3001, progress: 7,
+            url: 'https://lichess.org/@/Magnus/perf/blitz',
+        });
+    });
+});

package/clis/lichess/top.js

@@ -0,0 +1,46 @@
+// lichess top — top-N leaderboard for a given perf type.
+//
+// Hits `/api/player/top/<n>/<perf>`. Returns the leaderboard rows; usernames
+// round-trip into `lichess user` for full profile detail.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { LICHESS_BASE, lichessFetch, requireBoundedInt, requirePerf } from './utils.js';
+
+cli({
+    site: 'lichess',
+    name: 'top',
+    access: 'read',
+    description: 'Top-N Lichess leaderboard for a perf type (bullet/blitz/rapid/classical/...)',
+    domain: 'lichess.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'perf', positional: true, required: true, help: 'Perf type (bullet, blitz, rapid, classical, ultraBullet, chess960, ...)' },
+        { name: 'limit', type: 'int', default: 10, help: 'Top-N rows (1-200)' },
+    ],
+    columns: ['rank', 'username', 'id', 'title', 'rating', 'progress', 'patron', 'url'],
+    func: async (args) => {
+        const perf = requirePerf(args.perf);
+        const limit = requireBoundedInt(args.limit, 10, 200);
+        const url = `${LICHESS_BASE}/api/player/top/${limit}/${encodeURIComponent(perf)}`;
+        const body = await lichessFetch(url, 'lichess top');
+        const list = Array.isArray(body?.users) ? body.users : [];
+        if (!list.length) {
+            throw new EmptyResultError('lichess top', `Lichess returned no leaderboard rows for perf "${perf}".`);
+        }
+        return list.slice(0, limit).map((u, i) => {
+            const username = typeof u?.username === 'string' ? u.username : '';
+            const perfBlock = u?.perfs && typeof u.perfs === 'object' ? u.perfs[perf] ?? {} : {};
+            return {
+                rank: i + 1,
+                username,
+                id: typeof u?.id === 'string' ? u.id : null,
+                title: typeof u?.title === 'string' ? u.title : null,
+                rating: typeof perfBlock.rating === 'number' ? perfBlock.rating : null,
+                progress: typeof perfBlock.progress === 'number' ? perfBlock.progress : null,
+                patron: u?.patron === true,
+                url: username ? `${LICHESS_BASE}/@/${encodeURIComponent(username)}/perf/${encodeURIComponent(perf)}` : '',
+            };
+        });
+    },
+});

package/clis/lichess/user.js

@@ -0,0 +1,91 @@
+// lichess user — fetch a public Lichess player profile.
+//
+// Hits `/api/user/<username>`. Returns the agent-useful slice: handle, title,
+// flags (online / patron), counts, top-rated perf, profile bio.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { LICHESS_BASE, formatTimestamp, lichessFetch, requireUsername } from './utils.js';
+
+cli({
+    site: 'lichess',
+    name: 'user',
+    access: 'read',
+    description: 'Fetch a Lichess player profile by username (rating, perfs, counts)',
+    domain: 'lichess.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'username', positional: true, required: true, help: 'Lichess username (case-insensitive)' },
+    ],
+    columns: [
+        'username',
+        'id',
+        'title',
+        'patron',
+        'online',
+        'tosViolation',
+        'createdAt',
+        'seenAt',
+        'gamesAll',
+        'gamesWin',
+        'gamesLoss',
+        'gamesDraw',
+        'topPerfName',
+        'topPerfRating',
+        'topPerfGames',
+        'fideRating',
+        'country',
+        'bio',
+        'url',
+    ],
+    func: async (args) => {
+        const username = requireUsername(args.username);
+        const url = `${LICHESS_BASE}/api/user/${encodeURIComponent(username)}`;
+        const body = await lichessFetch(url, 'lichess user');
+        if (!body || typeof body !== 'object') {
+            throw new EmptyResultError('lichess user', `Lichess user "${username}" returned empty payload.`);
+        }
+        // Lichess marks closed accounts with `disabled: true` and strips data.
+        // Surface as EmptyResultError instead of a row of nulls (silent-fallback).
+        if (body.disabled === true) {
+            throw new EmptyResultError('lichess user', `Lichess user "${username}" is closed/disabled.`);
+        }
+        const perfs = body.perfs && typeof body.perfs === 'object' ? body.perfs : {};
+        // Pick the perf with the most games (excluding puzzle/storm/racer ephemera).
+        const playablePerfs = Object.entries(perfs).filter(([k, v]) => v && typeof v === 'object' && !['puzzle', 'storm', 'racer', 'streak'].includes(k));
+        let topPerfName = null;
+        let topPerfRating = null;
+        let topPerfGames = null;
+        for (const [name, p] of playablePerfs) {
+            const games = typeof p.games === 'number' ? p.games : 0;
+            if (topPerfGames == null || games > topPerfGames) {
+                topPerfName = name;
+                topPerfGames = games;
+                topPerfRating = typeof p.rating === 'number' ? p.rating : null;
+            }
+        }
+        const counts = body.count && typeof body.count === 'object' ? body.count : {};
+        const profile = body.profile && typeof body.profile === 'object' ? body.profile : {};
+        return [{
+            username: typeof body.username === 'string' ? body.username : username,
+            id: typeof body.id === 'string' ? body.id : null,
+            title: typeof body.title === 'string' ? body.title : null,
+            patron: body.patron === true,
+            online: body.online === true,
+            tosViolation: body.tosViolation === true,
+            createdAt: formatTimestamp(body.createdAt),
+            seenAt: formatTimestamp(body.seenAt),
+            gamesAll: typeof counts.all === 'number' ? counts.all : null,
+            gamesWin: typeof counts.win === 'number' ? counts.win : null,
+            gamesLoss: typeof counts.loss === 'number' ? counts.loss : null,
+            gamesDraw: typeof counts.draw === 'number' ? counts.draw : null,
+            topPerfName,
+            topPerfRating,
+            topPerfGames,
+            fideRating: typeof profile.fideRating === 'number' ? profile.fideRating : null,
+            country: typeof profile.country === 'string' ? profile.country : null,
+            bio: typeof profile.bio === 'string' ? profile.bio.trim() : null,
+            url: `${LICHESS_BASE}/@/${encodeURIComponent(typeof body.username === 'string' ? body.username : username)}`,
+        }];
+    },
+});

package/clis/lichess/utils.js

@@ -0,0 +1,97 @@
+// Shared helpers for the lichess.org public REST adapters.
+//
+// Lichess exposes a generous unauthenticated API at `lichess.org/api`. We keep
+// the surface narrow: `user` (profile) + `top` (per-perf top-N leaderboard).
+// No API key required; rate limit is 60 req/min per IP.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const LICHESS_BASE = 'https://lichess.org';
+const UA = 'opencli-lichess-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';
+
+// Lichess usernames are 2-30 chars: letters, digits, underscore, dash. Case-insensitive.
+const USERNAME_PATTERN = /^[A-Za-z0-9_-]{2,30}$/;
+
+// `perfType` values lichess accepts for the `/api/player/top/<n>/<perf>` endpoint.
+// Source: lichess-org/api docs.
+export const LICHESS_PERFS = new Set([
+    'ultraBullet', 'bullet', 'blitz', 'rapid', 'classical',
+    'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde',
+    'kingOfTheHill', 'racingKings', 'threeCheck',
+]);
+
+export function requireUsername(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) throw new ArgumentError('lichess username is required');
+    if (!USERNAME_PATTERN.test(raw)) {
+        throw new ArgumentError(
+            `lichess username "${value}" is not a valid handle`,
+            'Allowed: letters, digits, underscore, dash; length 2-30.',
+        );
+    }
+    return raw;
+}
+
+export function requirePerf(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) throw new ArgumentError('lichess perf is required (e.g. "blitz", "bullet", "rapid")');
+    if (!LICHESS_PERFS.has(raw)) {
+        throw new ArgumentError(
+            `lichess perf "${value}" is not recognised`,
+            `Allowed values: ${[...LICHESS_PERFS].join(', ')}.`,
+        );
+    }
+    return raw;
+}
+
+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(`lichess ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`lichess ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export async function lichessFetch(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 lichess.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Lichess returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Lichess throttles anonymous traffic at ~60 req/min; back off 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;
+}
+
+/** Format a lichess unix-ms timestamp as ISO date (YYYY-MM-DD). `null` when missing. */
+export function formatTimestamp(ms) {
+    if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return null;
+    const d = new Date(ms);
+    if (Number.isNaN(d.getTime())) return null;
+    return d.toISOString();
+}

package/clis/linkedin/search.js

@@ -1,5 +1,9 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+const LINKEDIN_DOMAIN = 'linkedin.com';
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 100;
+const MIN_START = 0;
 // ── Filter value mappings ──────────────────────────────────────────────
 const EXPERIENCE_LEVELS = {
     internship: '1',
@@ -66,6 +70,19 @@ function mapFilterValues(input, mapping, label) {
 function normalizeWhitespace(value) {
     return String(value ?? '').replace(/\s+/g, ' ').trim();
 }
+function parseIntegerArg(value, label, fallback, min, max = Infinity) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+        throw new ArgumentError(`${label} must be an integer, got ${JSON.stringify(value)}`);
+    }
+    if (parsed < min || parsed > max) {
+        const range = Number.isFinite(max) ? `between ${min} and ${max}` : `at least ${min}`;
+        throw new ArgumentError(`${label} must be ${range}, got ${parsed}`);
+    }
+    return parsed;
+}
 function decodeLinkedinRedirect(url) {
     if (!url)
         return '';
@@ -120,6 +137,31 @@ function buildVoyagerUrl(input, offset, count) {
         .replace(/%29/gi, ')');
     return '/voyager/api/voyagerJobsDashJobCards?' + params.toString() + '&query=' + query + '&start=' + offset;
 }
+function looksLinkedInAuthWallText(value) {
+    const text = String(value ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!text)
+        return false;
+    return /\b(sign in|log in|join linkedin)\b/.test(text) ||
+        /linkedin\.com\/(login|checkpoint|authwall)/i.test(text) ||
+        /\b(captcha|verification required)\b/.test(text) ||
+        /(请登录|登录领英|安全验证)/.test(text);
+}
+function buildLinkedInAuthProbeScript() {
+    return `(() => {
+      const text = [
+        window.location.href || '',
+        document.title || '',
+        document.body ? (document.body.innerText || '').slice(0, 4000) : '',
+      ].join('\\n');
+      return ${looksLinkedInAuthWallText.toString()}(text);
+    })()`;
+}
+async function assertLinkedInAuthenticated(page, context) {
+    const authRequired = await page.evaluate(buildLinkedInAuthProbeScript());
+    if (authRequired) {
+        throw new AuthRequiredError(LINKEDIN_DOMAIN, `${context} requires an active signed-in LinkedIn browser session`);
+    }
+}
 // ── Company ID resolution (requires DOM interaction) ──────────────────
 async function resolveCompanyIds(page, input) {
     const rawValues = parseCsvArg(input);
@@ -209,13 +251,25 @@ async function fetchJobCards(page, input) {
         const batch = await page.evaluate(`(async () => {
       const jsession = document.cookie.split(';').map(p => p.trim())
         .find(p => p.startsWith('JSESSIONID='))?.slice('JSESSIONID='.length);
-      if (!jsession) return { error: 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn in the browser.' };
+      if (!jsession) {
+        return {
+          authRequired: true,
+          error: 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn in the browser.'
+        };
+      }
 
       const csrf = jsession.replace(/^"|"$/g, '');
       const res = await fetch(${JSON.stringify(apiPath)}, {
         credentials: 'include',
         headers: { 'csrf-token': csrf, 'x-restli-protocol-version': '2.0.0' },
       });
+      if (res.status === 401 || res.status === 403) {
+        const text = await res.text();
+        return {
+          authRequired: true,
+          error: 'LinkedIn API authentication failed: HTTP ' + res.status + ' ' + text.slice(0, 200)
+        };
+      }
       if (!res.ok) {
         const text = await res.text();
         return { error: 'LinkedIn API error: HTTP ' + res.status + ' ' + text.slice(0, 200) };
@@ -223,6 +277,9 @@ async function fetchJobCards(page, input) {
       return res.json();
     })()`);
         if (!batch || batch.error) {
+            if (batch?.authRequired) {
+                throw new AuthRequiredError(LINKEDIN_DOMAIN, batch.error);
+            }
             throw new CommandExecutionError(batch?.error || 'LinkedIn search returned an unexpected response');
         }
         const elements = Array.isArray(batch?.elements) ? batch.elements : [];
@@ -259,17 +316,31 @@ async function fetchJobCards(page, input) {
     }));
 }
 // ── Job detail enrichment (--details flag) ────────────────────────────
+//
+// Per-row failures should NOT abort the whole list (--details enriches N rows;
+// partial failure is expected). But silent empty-string fields hide the failure
+// from callers — previously `catch {}` and the `if (!job.url)` early-return
+// both produced indistinguishable `description: '', apply_url: ''` payloads,
+// so users could not tell "fetch failed" from "upstream had no description".
+//
+// The fix: surface `null` instead of `''` for missing/failed rows, set
+// `detail_error` to a short reason ("no url" / "fetch failed: <message>" /
+// "missing description"), and log every failure to stderr with the offending
+// URL so debugging is possible. Successful rows have `detail_error: null`.
 async function enrichJobDetails(page, jobs) {
     const enriched = [];
     for (let i = 0; i < jobs.length; i++) {
         const job = jobs[i];
         console.error(`[opencli:linkedin] Fetching details ${i + 1}/${jobs.length}: ${job.title}`);
         if (!job.url) {
-            enriched.push({ ...job, description: '', apply_url: '' });
+            const reason = 'no url';
+            console.error(`[opencli:linkedin] Skipping detail for "${job.title}": ${reason}`);
+            enriched.push({ ...job, description: null, apply_url: null, detail_error: reason });
             continue;
         }
         try {
             await page.goto(job.url);
+            await assertLinkedInAuthenticated(page, 'LinkedIn job detail');
             await page.wait({ text: 'About the job', timeout: 8 });
             // Expand "Show more" button if present
             await page.evaluate(`(() => {
@@ -301,14 +372,25 @@ async function enrichJobDetails(page, jobs) {
 
         return { description, applyUrl: applyLink?.href || '' };
       })()`);
+            const description = normalizeWhitespace(detail?.description);
+            const apply_url = decodeLinkedinRedirect(String(detail?.applyUrl ?? ''));
+            // Empty description after a successful fetch is itself a
+            // recognizable signal — surface it via detail_error instead of
+            // silently emitting an empty string.
+            const detail_error = description ? null : 'missing description';
             enriched.push({
                 ...job,
-                description: normalizeWhitespace(detail?.description),
-                apply_url: decodeLinkedinRedirect(String(detail?.applyUrl ?? '')),
+                description: description || null,
+                apply_url: apply_url || null,
+                detail_error,
             });
         }
-        catch {
-            enriched.push({ ...job, description: '', apply_url: '' });
+        catch (err) {
+            if (err instanceof AuthRequiredError)
+                throw err;
+            const reason = `fetch failed: ${err?.message || err}`;
+            console.error(`[opencli:linkedin] Detail fetch failed for ${job.url}: ${reason}`);
+            enriched.push({ ...job, description: null, apply_url: null, detail_error: reason });
         }
     }
     return enriched;
@@ -320,7 +402,7 @@ cli({
     access: 'read',
     description: 'Search LinkedIn jobs',
     domain: 'www.linkedin.com',
-    strategy: Strategy.HEADER,
+    strategy: Strategy.COOKIE,
     browser: true,
     args: [
         { name: 'query', type: 'string', required: true, positional: true, help: 'Job search keywords' },
@@ -336,8 +418,8 @@ cli({
     ],
     columns: ['rank', 'title', 'company', 'location', 'listed', 'salary', 'url'],
     func: async (page, kwargs) => {
-        const limit = Math.max(1, Math.min(kwargs.limit ?? 10, 100));
-        const start = Math.max(0, kwargs.start ?? 0);
+        const limit = parseIntegerArg(kwargs.limit, '--limit', 10, MIN_LIMIT, MAX_LIMIT);
+        const start = parseIntegerArg(kwargs.start, '--start', 0, MIN_START);
         const includeDetails = Boolean(kwargs.details);
         const location = (kwargs.location ?? '').trim();
         const keywords = String(kwargs.query ?? '').trim();
@@ -347,6 +429,7 @@ cli({
         if (location)
             searchParams.set('location', location);
         await page.goto(`https://www.linkedin.com/jobs/search/?${searchParams.toString()}`);
+        await assertLinkedInAuthenticated(page, 'LinkedIn search');
         await page.wait({ text: 'Jobs', timeout: 10 });
         const companyIds = await resolveCompanyIds(page, kwargs.company);
         const input = {
@@ -366,3 +449,17 @@ cli({
         return enrichJobDetails(page, data);
     },
 });
+
+export const __test__ = {
+    parseCsvArg,
+    parseIntegerArg,
+    mapFilterValues,
+    decodeLinkedinRedirect,
+    looksLinkedInAuthWallText,
+    assertLinkedInAuthenticated,
+    enrichJobDetails,
+    EXPERIENCE_LEVELS,
+    JOB_TYPES,
+    DATE_POSTED,
+    REMOTE_TYPES,
+};