@jackwener/opencli 1.7.22 → 1.8.1

package/clis/chess/game.js

@@ -0,0 +1,114 @@
+/**
+ * Chess.com single-game detail by URL, via the internal callback
+ * endpoint `/callback/{live|daily}/game/{id}`. Returns the canonical
+ * PGN headers + move data plus per-player metadata.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { UA, formatDate, isPlainObject, parseGameUrl } from './utils.js';
+
+const CALLBACK_BASE = 'https://www.chess.com/callback';
+
+function stringOrEmpty(value) {
+    return typeof value === 'string' ? value : '';
+}
+
+function scalarOrEmpty(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? value : '';
+}
+
+export function summarizeGame({ kind, id, payload }) {
+    if (!isPlainObject(payload) || !isPlainObject(payload.game)) {
+        throw new CommandExecutionError('Chess.com callback returned no game payload');
+    }
+    const g = payload.game;
+    if (g.pgnHeaders !== undefined && !isPlainObject(g.pgnHeaders)) {
+        throw new CommandExecutionError('Chess.com callback returned malformed PGN headers');
+    }
+    if (payload.players !== undefined && !isPlainObject(payload.players)) {
+        throw new CommandExecutionError('Chess.com callback returned malformed player metadata');
+    }
+    const players = payload.players || {};
+    const byColor = {};
+    for (const slot of ['top', 'bottom']) {
+        const p = players[slot];
+        if (p !== undefined && !isPlainObject(p)) {
+            throw new CommandExecutionError('Chess.com callback returned malformed player metadata');
+        }
+        if (p?.color) byColor[p.color] = p;
+    }
+    const white = byColor.white || {};
+    const black = byColor.black || {};
+    const headers = g.pgnHeaders || {};
+    const whiteName = stringOrEmpty(white.username) || stringOrEmpty(headers.White);
+    const blackName = stringOrEmpty(black.username) || stringOrEmpty(headers.Black);
+    const result = stringOrEmpty(headers.Result);
+    if (!whiteName || !blackName || !result) {
+        throw new CommandExecutionError('Chess.com callback payload is missing stable game summary fields');
+    }
+    const headerDate = stringOrEmpty(headers.Date);
+    return {
+        kind,
+        game_id: id,
+        date: headerDate ? headerDate.replace(/\./g, '-') : formatDate(g.endTime),
+        white: whiteName,
+        white_rating: scalarOrEmpty(white.rating) || scalarOrEmpty(headers.WhiteElo),
+        black: blackName,
+        black_rating: scalarOrEmpty(black.rating) || scalarOrEmpty(headers.BlackElo),
+        result,
+        winner_color: stringOrEmpty(g.colorOfWinner),
+        termination: stringOrEmpty(headers.Termination) || stringOrEmpty(g.resultMessage),
+        eco: stringOrEmpty(headers.ECO),
+        time_control: stringOrEmpty(headers.TimeControl) || (typeof g.daysPerTurn === 'number' ? `${g.daysPerTurn}d/turn` : ''),
+        rated: g.isRated === true,
+        ply_count: g.plyCount ?? '',
+        url: `https://www.chess.com/game/${kind}/${id}`,
+    };
+}
+
+cli({
+    site: 'chess',
+    name: 'game',
+    access: 'read',
+    description: 'Chess.com single-game detail (white, black, result, ECO, time control) by full game URL',
+    domain: 'www.chess.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'game-url', type: 'string', required: true, positional: true, help: 'Full game URL, e.g. https://www.chess.com/game/live/168842570216' },
+    ],
+    columns: [
+        'kind', 'game_id', 'date',
+        'white', 'white_rating', 'black', 'black_rating',
+        'result', 'winner_color', 'termination',
+        'eco', 'time_control', 'rated', 'ply_count', 'url',
+    ],
+    func: async (kwargs) => {
+        const { kind, id } = parseGameUrl(kwargs['game-url']);
+        const url = `${CALLBACK_BASE}/${kind}/game/${id}`;
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': UA, accept: 'application/json' } });
+        } catch (error) {
+            throw new CommandExecutionError(`Failed to fetch Chess.com callback ${url}: ${error?.message || error}`);
+        }
+        if (!resp || typeof resp !== 'object') {
+            throw new CommandExecutionError(`Chess.com callback returned an invalid response object for ${url}`);
+        }
+        if (resp.status === 404) {
+            throw new EmptyResultError(`Chess.com has no ${kind} game with id ${id}`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`Chess.com callback returned HTTP ${resp.status} for ${url}`);
+        }
+        let payload;
+        try {
+            payload = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`Chess.com callback returned malformed JSON for ${url}: ${error?.message || error}`);
+        }
+        return [summarizeGame({ kind, id, payload })];
+    },
+});
+
+export const __test__ = { parseGameUrl, summarizeGame };

package/clis/chess/game.test.js

@@ -0,0 +1,178 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './game.js';
+
+const { summarizeGame } = await import('./game.js').then((m) => m.__test__);
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+function mockFetch(payload, status = 200) {
+    return vi.fn().mockResolvedValue({
+        ok: status === 200,
+        status,
+        json: () => Promise.resolve(payload),
+    });
+}
+
+describe('chess game command', () => {
+    it('summarizeGame maps the callback payload to the canonical row shape', () => {
+        const row = summarizeGame({
+            kind: 'live',
+            id: '999',
+            payload: {
+                game: {
+                    pgnHeaders: {
+                        Date: '2026.05.17',
+                        White: 'Hikaru',
+                        Black: 'tactic',
+                        Result: '1-0',
+                        ECO: 'A01',
+                        WhiteElo: 3454,
+                        BlackElo: 2869,
+                        TimeControl: '180',
+                        Termination: 'Hikaru won by resignation',
+                    },
+                    colorOfWinner: 'white',
+                    isRated: true,
+                    plyCount: 111,
+                    endTime: 1747584400,
+                },
+                players: {
+                    top: { username: 'tactic', color: 'black', rating: 2869 },
+                    bottom: { username: 'Hikaru', color: 'white', rating: 3454 },
+                },
+            },
+        });
+        expect(row).toMatchObject({
+            kind: 'live',
+            game_id: '999',
+            date: '2026-05-17',
+            white: 'Hikaru',
+            white_rating: 3454,
+            black: 'tactic',
+            black_rating: 2869,
+            result: '1-0',
+            winner_color: 'white',
+            termination: 'Hikaru won by resignation',
+            eco: 'A01',
+            time_control: '180',
+            rated: true,
+            ply_count: 111,
+            url: 'https://www.chess.com/game/live/999',
+        });
+    });
+
+    it('summarizeGame falls back to pgnHeaders when players are missing', () => {
+        const row = summarizeGame({
+            kind: 'daily',
+            id: '1',
+            payload: {
+                game: {
+                    pgnHeaders: { White: 'A', Black: 'B', Result: '1/2-1/2', WhiteElo: 1200, BlackElo: 1300 },
+                    colorOfWinner: '',
+                    isRated: false,
+                    daysPerTurn: 3,
+                },
+                players: {},
+            },
+        });
+        expect(row.white).toBe('A');
+        expect(row.black_rating).toBe(1300);
+        expect(row.time_control).toBe('3d/turn');
+        expect(row.rated).toBe(false);
+    });
+
+    it('summarizeGame throws CommandExecutionError on missing game payload', () => {
+        expect(() => summarizeGame({ kind: 'live', id: '1', payload: {} })).toThrow(CommandExecutionError);
+        expect(() => summarizeGame({ kind: 'live', id: '1', payload: null })).toThrow(CommandExecutionError);
+    });
+
+    it('summarizeGame throws CommandExecutionError on malformed nested payloads', () => {
+        expect(() => summarizeGame({
+            kind: 'live',
+            id: '1',
+            payload: { game: { pgnHeaders: [] } },
+        })).toThrow(CommandExecutionError);
+        expect(() => summarizeGame({
+            kind: 'live',
+            id: '1',
+            payload: { game: { pgnHeaders: { White: 'A', Black: 'B' } }, players: [] },
+        })).toThrow(CommandExecutionError);
+    });
+
+    it('summarizeGame requires stable players and result evidence', () => {
+        expect(() => summarizeGame({
+            kind: 'live',
+            id: '1',
+            payload: { game: { pgnHeaders: { White: 'A', Black: 'B' } }, players: {} },
+        })).toThrow(CommandExecutionError);
+        expect(() => summarizeGame({
+            kind: 'live',
+            id: '1',
+            payload: { game: { pgnHeaders: { White: 'A', Result: '1-0' } }, players: {} },
+        })).toThrow(CommandExecutionError);
+    });
+
+    it('command fetches the callback URL and returns a single row', async () => {
+        const fetchMock = mockFetch({
+            game: { pgnHeaders: { White: 'A', Black: 'B', Result: '1-0', WhiteElo: 100, BlackElo: 90 } },
+            players: {},
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('chess/game');
+        const rows = await cmd.func({ 'game-url': 'https://www.chess.com/game/live/42' });
+        expect(rows).toHaveLength(1);
+        expect(rows[0].url).toBe('https://www.chess.com/game/live/42');
+        expect(fetchMock).toHaveBeenCalledWith(
+            'https://www.chess.com/callback/live/game/42',
+            expect.objectContaining({ headers: expect.any(Object) }),
+        );
+    });
+
+    it('command surfaces 404 as EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 404 }));
+        const cmd = getRegistry().get('chess/game');
+        await expect(cmd.func({ 'game-url': 'https://www.chess.com/game/live/1' }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('command surfaces non-2xx as CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500 }));
+        const cmd = getRegistry().get('chess/game');
+        await expect(cmd.func({ 'game-url': 'https://www.chess.com/game/live/1' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('command maps fetch and JSON failures to CommandExecutionError', async () => {
+        const cmd = getRegistry().get('chess/game');
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new TypeError('network down')));
+        await expect(cmd.func({ 'game-url': 'https://www.chess.com/game/live/1' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: () => Promise.reject(new SyntaxError('bad json')),
+        }));
+        await expect(cmd.func({ 'game-url': 'https://www.chess.com/game/live/1' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('command maps wrong-shape callback JSON to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', mockFetch([]));
+        const cmd = getRegistry().get('chess/game');
+        await expect(cmd.func({ 'game-url': 'https://www.chess.com/game/live/1' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects invalid URL with ArgumentError before any fetch', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('chess/game');
+        await expect(cmd.func({ 'game-url': 'not-a-url' })).rejects.toBeInstanceOf(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+});

package/clis/chess/games.js

@@ -0,0 +1,67 @@
+/**
+ * Chess.com recent games from monthly archives. Walks the archive
+ * list newest-first and fetches as few months as needed to fill --limit.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { chessApi, validateUsername, mapGameRow } from './utils.js';
+
+const MAX_LIMIT = 100;
+const MAX_ARCHIVE_FETCHES = 6;
+
+function parseLimit(value) {
+    if (value === undefined || value === null || value === '') return 10;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be an integer between 1 and ${MAX_LIMIT}`);
+    }
+    return limit;
+}
+
+cli({
+    site: 'chess',
+    name: 'games',
+    access: 'read',
+    description: 'Chess.com recent games for a player, newest first',
+    domain: 'api.chess.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'username', type: 'string', required: true, positional: true, help: 'Chess.com username' },
+        { name: 'limit', type: 'int', default: 10, help: `Number of recent games (1-${MAX_LIMIT})` },
+    ],
+    columns: ['date', 'time_class', 'rated', 'my_color', 'my_rating', 'my_result', 'opponent', 'opponent_rating', 'accuracy_white', 'accuracy_black', 'eco', 'opening_name', 'url'],
+    func: async (kwargs) => {
+        const username = validateUsername(kwargs.username);
+        const limit = parseLimit(kwargs.limit);
+        const archivesList = await chessApi(`/player/${encodeURIComponent(username)}/games/archives`);
+        if (!Array.isArray(archivesList.archives)) {
+            throw new CommandExecutionError('Chess.com archives payload is missing archives array');
+        }
+        const archives = archivesList.archives.slice().reverse();
+        if (archives.length === 0) {
+            throw new EmptyResultError(`Chess.com has no game archives for ${username}`);
+        }
+        const rows = [];
+        for (let i = 0; i < archives.length && i < MAX_ARCHIVE_FETCHES && rows.length < limit; i++) {
+            if (typeof archives[i] !== 'string' || !archives[i].startsWith('https://api.chess.com/pub/player/')) {
+                throw new CommandExecutionError('Chess.com archives payload contains an unexpected archive URL');
+            }
+            const monthly = await chessApi(archives[i]);
+            if (!Array.isArray(monthly.games)) {
+                throw new CommandExecutionError('Chess.com monthly archive payload is missing games array');
+            }
+            const games = monthly.games.slice().reverse();
+            for (const g of games) {
+                rows.push(mapGameRow(g, username));
+                if (rows.length >= limit) break;
+            }
+        }
+        if (rows.length === 0) {
+            throw new EmptyResultError(`Chess.com has games archives for ${username} but no games in the most recent ${MAX_ARCHIVE_FETCHES} months`);
+        }
+        return rows.slice(0, limit);
+    },
+});
+
+export const __test__ = { parseLimit };

package/clis/chess/games.test.js

@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './games.js';
+
+const { parseLimit } = await import('./games.js').then((m) => m.__test__);
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+function fetchFor(map) {
+    return vi.fn().mockImplementation((url) => {
+        if (map.has(url)) {
+            return Promise.resolve({ ok: true, status: 200, json: () => Promise.resolve(map.get(url)) });
+        }
+        return Promise.resolve({ ok: false, status: 404 });
+    });
+}
+
+function game(white, whiteRating, black, blackRating, endTime, extra = {}) {
+    return {
+        url: `https://www.chess.com/game/live/${endTime}`,
+        end_time: endTime,
+        time_class: 'blitz',
+        rated: true,
+        eco: 'C50',
+        white: { username: white, rating: whiteRating, result: 'win' },
+        black: { username: black, rating: blackRating, result: 'resigned' },
+        ...extra,
+    };
+}
+
+describe('chess games command', () => {
+    it('parseLimit accepts 1-100, rejects everything else', () => {
+        expect(parseLimit(undefined)).toBe(10);
+        expect(parseLimit(1)).toBe(1);
+        expect(parseLimit(100)).toBe(100);
+        expect(() => parseLimit(0)).toThrow(ArgumentError);
+        expect(() => parseLimit(101)).toThrow(ArgumentError);
+        expect(() => parseLimit(1.5)).toThrow(ArgumentError);
+        expect(() => parseLimit('abc')).toThrow(ArgumentError);
+    });
+
+    it('returns recent games newest-first sliced to --limit', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/hikaru/games/archives', {
+                archives: ['https://api.chess.com/pub/player/hikaru/games/2026/04', 'https://api.chess.com/pub/player/hikaru/games/2026/05'],
+            }],
+            ['https://api.chess.com/pub/player/hikaru/games/2026/05', {
+                games: [
+                    game('Hikaru', 3286, 'A', 2900, 1777737000),
+                    game('Hikaru', 3286, 'B', 2950, 1777737500),
+                    game('Hikaru', 3286, 'C', 3000, 1777737900),
+                ],
+            }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        const rows = await cmd.func({ username: 'Hikaru', limit: 2 });
+        expect(rows).toHaveLength(2);
+        // archive is reversed (newest month first), games within are reversed
+        // so the first row corresponds to the LAST game in the JSON array.
+        expect(rows[0].opponent).toBe('C');
+        expect(rows[1].opponent).toBe('B');
+    });
+
+    it('walks multiple months until --limit is filled', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/hikaru/games/archives', {
+                archives: ['https://api.chess.com/pub/player/hikaru/games/2026/03', 'https://api.chess.com/pub/player/hikaru/games/2026/04'],
+            }],
+            ['https://api.chess.com/pub/player/hikaru/games/2026/04', {
+                games: [game('Hikaru', 3286, 'A', 2900, 1777737000)],
+            }],
+            ['https://api.chess.com/pub/player/hikaru/games/2026/03', {
+                games: [game('Hikaru', 3286, 'B', 2950, 1774000000)],
+            }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        const rows = await cmd.func({ username: 'Hikaru', limit: 2 });
+        expect(rows.map((r) => r.opponent)).toEqual(['A', 'B']);
+    });
+
+    it('throws EmptyResultError when archives list is empty', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/someuser/games/archives', { archives: [] }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        await expect(cmd.func({ username: 'someuser', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('throws CommandExecutionError when archives payload is wrong-shape', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/someuser/games/archives', { archives: {} }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        await expect(cmd.func({ username: 'someuser', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when monthly archive games payload is wrong-shape', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/hikaru/games/archives', {
+                archives: ['https://api.chess.com/pub/player/hikaru/games/2026/05'],
+            }],
+            ['https://api.chess.com/pub/player/hikaru/games/2026/05', { games: null }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        await expect(cmd.func({ username: 'Hikaru', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when a game row lacks stable identity', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/hikaru/games/archives', {
+                archives: ['https://api.chess.com/pub/player/hikaru/games/2026/05'],
+            }],
+            ['https://api.chess.com/pub/player/hikaru/games/2026/05', {
+                games: [{
+                    end_time: 1777737000,
+                    white: { username: 'Hikaru', rating: 3286, result: 'win' },
+                    black: { username: 'A', rating: 2900, result: 'resigned' },
+                }],
+            }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        await expect(cmd.func({ username: 'Hikaru', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when a game row does not include the requested player', async () => {
+        const map = new Map([
+            ['https://api.chess.com/pub/player/hikaru/games/archives', {
+                archives: ['https://api.chess.com/pub/player/hikaru/games/2026/05'],
+            }],
+            ['https://api.chess.com/pub/player/hikaru/games/2026/05', {
+                games: [game('A', 2900, 'B', 2800, 1777737000)],
+            }],
+        ]);
+        vi.stubGlobal('fetch', fetchFor(map));
+        const cmd = getRegistry().get('chess/games');
+        await expect(cmd.func({ username: 'Hikaru', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws ArgumentError on invalid username before any fetch', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('chess/games');
+        await expect(cmd.func({ username: 'a b', limit: 5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('registers with the expected columns', () => {
+        const cmd = getRegistry().get('chess/games');
+        expect(cmd?.columns).toEqual([
+            'date', 'time_class', 'rated', 'my_color', 'my_rating', 'my_result',
+            'opponent', 'opponent_rating', 'accuracy_white', 'accuracy_black',
+            'eco', 'opening_name', 'url',
+        ]);
+    });
+});

package/clis/chess/stats.js

@@ -0,0 +1,32 @@
+/**
+ * Chess.com player stats across game kinds (rapid / blitz / bullet /
+ * daily / chess960 / etc) via the public stats endpoint.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { chessApi, validateUsername, summarizeStats } from './utils.js';
+
+const KINDS = ['chess_rapid', 'chess_blitz', 'chess_bullet', 'chess_daily', 'chess960_daily', 'chess_daily_960'];
+
+cli({
+    site: 'chess',
+    name: 'stats',
+    access: 'read',
+    description: 'Chess.com player ratings + win/loss record across game kinds',
+    domain: 'api.chess.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'username', type: 'string', required: true, positional: true, help: 'Chess.com username (case-insensitive)' },
+    ],
+    columns: ['kind', 'rating_current', 'rating_best', 'wins', 'losses', 'draws'],
+    func: async (kwargs) => {
+        const username = validateUsername(kwargs.username);
+        const stats = await chessApi(`/player/${encodeURIComponent(username)}/stats`);
+        const rows = KINDS.map((k) => summarizeStats(stats, k)).filter(Boolean);
+        if (rows.length === 0) {
+            throw new EmptyResultError(`Chess.com returned no stats for ${username}`);
+        }
+        return rows;
+    },
+});

package/clis/chess/stats.test.js

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './stats.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+function mockFetch(body) {
+    return vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(body),
+    });
+}
+
+describe('chess stats command', () => {
+    it('rejects empty username via validateUsername', async () => {
+        const cmd = getRegistry().get('chess/stats');
+        await expect(cmd.func({ username: '' })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('rejects invalid username characters', async () => {
+        const cmd = getRegistry().get('chess/stats');
+        await expect(cmd.func({ username: 'user name' })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('returns one row per known game kind populated in the stats response', async () => {
+        const fetchMock = mockFetch({
+            chess_rapid: { last: { rating: 1700 }, best: { rating: 1800 }, record: { win: 50, loss: 20, draw: 5 } },
+            chess_blitz: { last: { rating: 1500 }, best: { rating: 1600 }, record: { win: 100, loss: 80, draw: 10 } },
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('chess/stats');
+        const rows = await cmd.func({ username: 'someuser' });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].kind).toBe('rapid');
+        expect(rows[1].kind).toBe('blitz');
+        expect(fetchMock).toHaveBeenCalledWith(
+            'https://api.chess.com/pub/player/someuser/stats',
+            expect.objectContaining({ headers: expect.any(Object) }),
+        );
+    });
+
+    it('lowercases username in the URL', async () => {
+        const fetchMock = mockFetch({ chess_rapid: { last: { rating: 1 }, best: {}, record: {} } });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('chess/stats');
+        await cmd.func({ username: 'MixedCase' });
+        expect(fetchMock).toHaveBeenCalledWith(
+            'https://api.chess.com/pub/player/mixedcase/stats',
+            expect.any(Object),
+        );
+    });
+
+    it('throws EmptyResultError when the stats response has no known kinds', async () => {
+        vi.stubGlobal('fetch', mockFetch({}));
+        const cmd = getRegistry().get('chess/stats');
+        await expect(cmd.func({ username: 'someuser' })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('throws CommandExecutionError when a populated stats kind is malformed', async () => {
+        vi.stubGlobal('fetch', mockFetch({ chess_rapid: 'bad' }));
+        const cmd = getRegistry().get('chess/stats');
+        await expect(cmd.func({ username: 'someuser' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError on HTTP 404', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 404 }));
+        const cmd = getRegistry().get('chess/stats');
+        await expect(cmd.func({ username: 'someuser' })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('registers with the expected columns', () => {
+        const cmd = getRegistry().get('chess/stats');
+        expect(cmd?.columns).toEqual(['kind', 'rating_current', 'rating_best', 'wins', 'losses', 'draws']);
+    });
+});