@jackwener/opencli 1.8.0 → 1.8.1

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']);
+    });
+});

package/clis/chess/utils.js

@@ -0,0 +1,170 @@
+/**
+ * Shared helpers for the public Chess.com REST API
+ * (https://api.chess.com/pub/). No auth, no rate-limit headers.
+ */
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const API_BASE = 'https://api.chess.com/pub';
+export const UA = 'Mozilla/5.0 (compatible; opencli/1.0)';
+
+const USERNAME_RE = /^[a-zA-Z0-9_-]{3,25}$/;
+const GAME_URL_RE = /^https:\/\/www\.chess\.com\/game\/(live|daily)\/(\d+)/i;
+
+export function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isOptionalPlainObject(value) {
+    return value === undefined || value === null || isPlainObject(value);
+}
+
+export function validateUsername(value) {
+    const s = String(value ?? '').trim().toLowerCase();
+    if (!s) throw new ArgumentError('<username> is required');
+    if (!USERNAME_RE.test(s)) {
+        throw new ArgumentError(`Invalid Chess.com username "${value}"`, 'Usernames are 3-25 chars: a-z, 0-9, hyphen, underscore.');
+    }
+    return s;
+}
+
+export function parseGameUrl(value) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError('<game-url> is required');
+    const m = s.match(GAME_URL_RE);
+    if (!m) {
+        throw new ArgumentError(
+            `Invalid Chess.com game URL: "${value}"`,
+            'Expected https://www.chess.com/game/live/<id> or https://www.chess.com/game/daily/<id>.',
+        );
+    }
+    return { kind: m[1].toLowerCase(), id: m[2] };
+}
+
+export async function chessApi(path, fetchImpl = fetch) {
+    const url = path.startsWith('http') ? path : `${API_BASE}${path}`;
+    let resp;
+    try {
+        resp = await fetchImpl(url, { headers: { 'User-Agent': UA, accept: 'application/json' } });
+    } catch (error) {
+        throw new CommandExecutionError(`Failed to fetch Chess.com API ${url}: ${error?.message || error}`);
+    }
+    if (!resp || typeof resp !== 'object') {
+        throw new CommandExecutionError(`Chess.com API returned an invalid response object for ${url}`);
+    }
+    if (resp.status === 404) throw new EmptyResultError(`Chess.com returned 404 for ${url}`);
+    if (!resp.ok) throw new CommandExecutionError(`Chess.com API returned HTTP ${resp.status} for ${url}`);
+    let payload;
+    try {
+        payload = await resp.json();
+    } catch (error) {
+        throw new CommandExecutionError(`Chess.com API returned malformed JSON for ${url}: ${error?.message || error}`);
+    }
+    if (!isPlainObject(payload)) {
+        throw new CommandExecutionError(`Chess.com API returned an unexpected payload shape for ${url}`);
+    }
+    return payload;
+}
+
+/** Pull rating + record fields out of a stats sub-object (`chess_rapid` etc). */
+export function summarizeStats(stats, kind) {
+    const k = stats?.[kind];
+    if (!k) return null;
+    if (!isPlainObject(k)) {
+        throw new CommandExecutionError(`Chess.com stats payload for ${kind} is not an object`);
+    }
+    if (!isOptionalPlainObject(k.last)) {
+        throw new CommandExecutionError(`Chess.com stats payload for ${kind}.last is not an object`);
+    }
+    if (!isOptionalPlainObject(k.best)) {
+        throw new CommandExecutionError(`Chess.com stats payload for ${kind}.best is not an object`);
+    }
+    if (!isOptionalPlainObject(k.record)) {
+        throw new CommandExecutionError(`Chess.com stats payload for ${kind}.record is not an object`);
+    }
+    const record = isPlainObject(k.record) ? k.record : {};
+    return {
+        kind: kind.replace(/^chess_/, ''),
+        rating_current: k.last?.rating ?? '',
+        rating_best: k.best?.rating ?? '',
+        wins: record.win ?? '',
+        losses: record.loss ?? '',
+        draws: record.draw ?? '',
+    };
+}
+
+/** Parse an end_time epoch (seconds) into YYYY-MM-DD. */
+export function formatDate(epochSeconds) {
+    if (!epochSeconds || typeof epochSeconds !== 'number') return '';
+    return new Date(epochSeconds * 1000).toISOString().slice(0, 10);
+}
+
+/**
+ * Pull "Reti Opening: Nimzo-Larsen Variation" out of the Chess.com eco URL
+ * (`https://www.chess.com/openings/Reti-Opening-Nimzo-Larsen-Variation-2...g6-...`).
+ * Returns '' for short-code eco values (`A01`) where no name is encoded.
+ */
+export function openingName(eco) {
+    if (typeof eco !== 'string' || !eco.startsWith('http')) return '';
+    const tail = eco.replace(/\/+$/, '').split('/').pop() || '';
+    if (!tail) return '';
+    const namePart = tail.match(/^([^.]+?)(?:-\d|\.\.\.|$)/);
+    const cleaned = (namePart ? namePart[1] : tail).replace(/-/g, ' ').trim();
+    return cleaned;
+}
+
+/**
+ * Map a Chess.com game record (from the monthly archive) to a flat row.
+ * The viewer perspective controls win/loss orientation.
+ */
+export function mapGameRow(game, viewerUsername) {
+    if (!isPlainObject(game)) {
+        throw new CommandExecutionError('Chess.com game archive entry is not an object');
+    }
+    if (typeof game.url !== 'string' || !/^https:\/\/www\.chess\.com\/game\/(?:live|daily)\/\d+(?:$|[/?#])/i.test(game.url)) {
+        throw new CommandExecutionError('Chess.com game archive entry is missing a stable game URL');
+    }
+    const white = game?.white || {};
+    const black = game?.black || {};
+    if (!isPlainObject(white) || !isPlainObject(black)) {
+        throw new CommandExecutionError('Chess.com game archive entry has malformed player objects');
+    }
+    if (typeof white.username !== 'string' || !white.username.trim() || typeof black.username !== 'string' || !black.username.trim()) {
+        throw new CommandExecutionError('Chess.com game archive entry is missing stable player identities');
+    }
+    const viewerLower = String(viewerUsername || '').toLowerCase();
+    const viewerIsWhite = String(white.username || '').toLowerCase() === viewerLower;
+    const viewerIsBlack = String(black.username || '').toLowerCase() === viewerLower;
+    if (!viewerIsWhite && !viewerIsBlack) {
+        throw new CommandExecutionError('Chess.com game archive entry does not include the requested player');
+    }
+    const me = viewerIsWhite ? white : black;
+    const opp = viewerIsWhite ? black : white;
+    const eco = game?.eco || '';
+    return {
+        date: formatDate(game?.end_time),
+        time_class: game?.time_class || '',
+        rated: game?.rated === true,
+        my_color: viewerIsWhite ? 'white' : 'black',
+        my_rating: me?.rating ?? '',
+        my_result: me?.result || '',
+        opponent: opp?.username || '',
+        opponent_rating: opp?.rating ?? '',
+        accuracy_white: typeof game?.accuracies?.white === 'number' ? game.accuracies.white : '',
+        accuracy_black: typeof game?.accuracies?.black === 'number' ? game.accuracies.black : '',
+        eco,
+        opening_name: openingName(eco),
+        url: game?.url || '',
+    };
+}
+
+export const __test__ = {
+    validateUsername,
+    parseGameUrl,
+    isPlainObject,
+    isOptionalPlainObject,
+    chessApi,
+    summarizeStats,
+    formatDate,
+    mapGameRow,
+    openingName,
+};

package/clis/chess/utils.test.js

@@ -0,0 +1,230 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { __test__ } from './utils.js';
+
+const { validateUsername, parseGameUrl, chessApi, summarizeStats, formatDate, mapGameRow, openingName } = __test__;
+
+describe('chess utils', () => {
+    it('validateUsername lowercases and accepts 3-25 char usernames', () => {
+        expect(validateUsername('Hikaru')).toBe('hikaru');
+        expect(validateUsername('MagnusCarlsen')).toBe('magnuscarlsen');
+        expect(validateUsername('a-b_c')).toBe('a-b_c');
+    });
+
+    it('validateUsername rejects empty / too-short / invalid chars', () => {
+        expect(() => validateUsername('')).toThrow(ArgumentError);
+        expect(() => validateUsername('ab')).toThrow(ArgumentError);
+        expect(() => validateUsername('user name')).toThrow(ArgumentError);
+        expect(() => validateUsername('a'.repeat(30))).toThrow(ArgumentError);
+    });
+
+    it('parseGameUrl parses both live and daily game URL forms', () => {
+        expect(parseGameUrl('https://www.chess.com/game/live/168842570216'))
+            .toEqual({ kind: 'live', id: '168842570216' });
+        expect(parseGameUrl('https://www.chess.com/game/daily/947761777'))
+            .toEqual({ kind: 'daily', id: '947761777' });
+        expect(parseGameUrl('https://www.chess.com/game/LIVE/1'))
+            .toEqual({ kind: 'live', id: '1' });
+    });
+
+    it('parseGameUrl strips trailing path / query off the URL', () => {
+        expect(parseGameUrl('https://www.chess.com/game/live/123/something?ref=share'))
+            .toEqual({ kind: 'live', id: '123' });
+    });
+
+    it('parseGameUrl rejects empty / non-URL / unsupported-kind inputs', () => {
+        expect(() => parseGameUrl('')).toThrow(ArgumentError);
+        expect(() => parseGameUrl('   ')).toThrow(ArgumentError);
+        expect(() => parseGameUrl('123')).toThrow(ArgumentError);
+        expect(() => parseGameUrl('https://www.chess.com/club/123')).toThrow(ArgumentError);
+        expect(() => parseGameUrl('https://lichess.org/abc')).toThrow(ArgumentError);
+    });
+
+    it('summarizeStats projects rating + record fields', () => {
+        const stats = {
+            chess_rapid: {
+                last: { rating: 1600 },
+                best: { rating: 1800 },
+                record: { win: 100, loss: 50, draw: 10 },
+            },
+        };
+        expect(summarizeStats(stats, 'chess_rapid')).toEqual({
+            kind: 'rapid',
+            rating_current: 1600,
+            rating_best: 1800,
+            wins: 100,
+            losses: 50,
+            draws: 10,
+        });
+    });
+
+    it('summarizeStats returns null for missing kind', () => {
+        expect(summarizeStats({}, 'chess_rapid')).toBeNull();
+        expect(summarizeStats({ chess_blitz: {} }, 'chess_rapid')).toBeNull();
+    });
+
+    it('summarizeStats typed-fails malformed populated kind objects', () => {
+        expect(() => summarizeStats({ chess_rapid: 'bad' }, 'chess_rapid')).toThrow(CommandExecutionError);
+        expect(() => summarizeStats({ chess_rapid: { record: [] } }, 'chess_rapid')).toThrow(CommandExecutionError);
+    });
+
+    it('summarizeStats coerces missing numeric fields to empty string', () => {
+        const row = summarizeStats({ chess_daily: { last: {}, record: {} } }, 'chess_daily');
+        expect(row).toEqual({
+            kind: 'daily',
+            rating_current: '',
+            rating_best: '',
+            wins: '',
+            losses: '',
+            draws: '',
+        });
+    });
+
+    it('formatDate converts epoch seconds to YYYY-MM-DD', () => {
+        expect(formatDate(1777737679)).toBe('2026-05-02');
+        expect(formatDate(0)).toBe('');
+        expect(formatDate(null)).toBe('');
+        expect(formatDate('not-a-number')).toBe('');
+    });
+
+    it('mapGameRow returns rows from the viewer perspective when viewer is white', () => {
+        const game = {
+            url: 'https://www.chess.com/game/live/123',
+            end_time: 1777737679,
+            time_class: 'blitz',
+            rated: true,
+            eco: 'C50',
+            accuracies: { white: 87.73, black: 80.23 },
+            white: { username: 'Hikaru', rating: 3286, result: 'win' },
+            black: { username: 'Magnus', rating: 2900, result: 'resigned' },
+        };
+        expect(mapGameRow(game, 'Hikaru')).toEqual({
+            date: '2026-05-02',
+            time_class: 'blitz',
+            rated: true,
+            my_color: 'white',
+            my_rating: 3286,
+            my_result: 'win',
+            opponent: 'Magnus',
+            opponent_rating: 2900,
+            accuracy_white: 87.73,
+            accuracy_black: 80.23,
+            eco: 'C50',
+            opening_name: '',
+            url: 'https://www.chess.com/game/live/123',
+        });
+    });
+
+    it('mapGameRow leaves accuracy fields empty when chess.com did not compute them', () => {
+        const game = {
+            url: 'https://www.chess.com/game/live/123',
+            white: { username: 'A', rating: 1, result: 'win' },
+            black: { username: 'B', rating: 1, result: 'resigned' },
+        };
+        const row = mapGameRow(game, 'A');
+        expect(row.accuracy_white).toBe('');
+        expect(row.accuracy_black).toBe('');
+    });
+
+    it('mapGameRow parses opening_name from the chess.com eco URL', () => {
+        const game = {
+            url: 'https://www.chess.com/game/live/123',
+            eco: 'https://www.chess.com/openings/Reti-Opening-Nimzo-Larsen-Variation-2...g6-3.Bb2-Bg7-4.d4',
+            white: { username: 'A', rating: 1, result: 'win' },
+            black: { username: 'B', rating: 1, result: 'resigned' },
+        };
+        const row = mapGameRow(game, 'A');
+        expect(row.opening_name).toBe('Reti Opening Nimzo Larsen Variation');
+    });
+
+    it('openingName helper returns clean human-readable name from URL form', () => {
+        expect(openingName('https://www.chess.com/openings/Sicilian-Defense')).toBe('Sicilian Defense');
+        expect(openingName('https://www.chess.com/openings/Kings-Indian-Defense-Semi-Classical-Variation...7.O-O'))
+            .toBe('Kings Indian Defense Semi Classical Variation');
+        expect(openingName('https://www.chess.com/openings/French-Defense-Advance-Variation-3...c5-4.c3'))
+            .toBe('French Defense Advance Variation');
+    });
+
+    it('openingName returns empty for short-code eco or missing input', () => {
+        expect(openingName('A01')).toBe('');
+        expect(openingName('')).toBe('');
+        expect(openingName(undefined)).toBe('');
+        expect(openingName(null)).toBe('');
+    });
+
+    it('mapGameRow flips perspective when viewer is black', () => {
+        const game = {
+            url: 'https://www.chess.com/game/live/123',
+            white: { username: 'Hikaru', rating: 3286, result: 'win' },
+            black: { username: 'Magnus', rating: 2900, result: 'resigned' },
+        };
+        const row = mapGameRow(game, 'Magnus');
+        expect(row.my_color).toBe('black');
+        expect(row.my_result).toBe('resigned');
+        expect(row.opponent).toBe('Hikaru');
+    });
+
+    it('mapGameRow matches viewer case-insensitively', () => {
+        const game = {
+            url: 'https://www.chess.com/game/live/123',
+            white: { username: 'Hikaru', rating: 3286, result: 'win' },
+            black: { username: 'Magnus', rating: 2900, result: 'resigned' },
+        };
+        expect(mapGameRow(game, 'hikaru').my_color).toBe('white');
+        expect(mapGameRow(game, 'MAGNUS').my_color).toBe('black');
+    });
+
+    it('mapGameRow typed-fails when viewer is neither player', () => {
+        const game = {
+            url: 'https://www.chess.com/game/live/123',
+            white: { username: 'A', rating: 1000, result: 'win' },
+            black: { username: 'B', rating: 1100, result: 'resigned' },
+        };
+        expect(() => mapGameRow(game, 'C')).toThrow(CommandExecutionError);
+    });
+
+    it('mapGameRow handles missing optional fields without throwing', () => {
+        const row = mapGameRow({
+            url: 'https://www.chess.com/game/live/123',
+            white: { username: 'x' },
+            black: { username: 'y' },
+        }, 'x');
+        expect(row.date).toBe('');
+        expect(row.url).toBe('https://www.chess.com/game/live/123');
+        expect(row.eco).toBe('');
+    });
+
+    it('mapGameRow typed-fails missing stable URL or player identity', () => {
+        expect(() => mapGameRow({
+            white: { username: 'x' },
+            black: { username: 'y' },
+        }, 'x')).toThrow(CommandExecutionError);
+        expect(() => mapGameRow({
+            url: 'https://www.chess.com/game/live/123',
+            white: { username: 'x' },
+            black: {},
+        }, 'x')).toThrow(CommandExecutionError);
+    });
+
+    it('chessApi maps network, malformed JSON, and wrong-shape payloads to typed errors', async () => {
+        await expect(chessApi('/x', async () => { throw new TypeError('network down'); }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(chessApi('/x', async () => ({
+            ok: true,
+            status: 200,
+            json: async () => { throw new SyntaxError('bad json'); },
+        }))).rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(chessApi('/x', async () => ({
+            ok: true,
+            status: 200,
+            json: async () => [],
+        }))).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('chessApi preserves 404 as empty and non-2xx as command execution errors', async () => {
+        await expect(chessApi('/x', async () => ({ ok: false, status: 404 })))
+            .rejects.toBeInstanceOf(EmptyResultError);
+        await expect(chessApi('/x', async () => ({ ok: false, status: 500 })))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});

package/clis/confluence/commands.test.js

@@ -0,0 +1,195 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it, afterEach, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './page.js';
+import './search.js';
+import './create.js';
+import './update.js';
+
+const ENV_KEYS = [
+    'ATLASSIAN_CONFLUENCE_BASE_URL',
+    'ATLASSIAN_DEPLOYMENT',
+    'ATLASSIAN_EMAIL',
+    'ATLASSIAN_API_TOKEN',
+    'ATLASSIAN_USERNAME',
+    'ATLASSIAN_PASSWORD',
+    'ATLASSIAN_PAT',
+];
+
+function clearEnv() {
+    for (const key of ENV_KEYS) delete process.env[key];
+}
+
+function setCloudEnv() {
+    clearEnv();
+    process.env.ATLASSIAN_CONFLUENCE_BASE_URL = 'https://team.atlassian.net/wiki';
+    process.env.ATLASSIAN_DEPLOYMENT = 'cloud';
+    process.env.ATLASSIAN_EMAIL = 'bot@example.com';
+    process.env.ATLASSIAN_API_TOKEN = 'secret';
+}
+
+function jsonResponse(body) {
+    return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+}
+
+async function withTempMarkdown(markdown, fn) {
+    const dir = await mkdtemp(join(tmpdir(), 'opencli-confluence-'));
+    const file = join(dir, 'doc.md');
+    await writeFile(file, markdown);
+    try {
+        return await fn(file);
+    } finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+
+afterEach(() => {
+    clearEnv();
+    vi.unstubAllGlobals();
+});
+
+describe('confluence commands', () => {
+    it('registers expected REST commands', () => {
+        for (const name of ['page', 'search', 'create', 'update']) {
+            const cmd = getRegistry().get(`confluence/${name}`);
+            expect(cmd).toBeDefined();
+            expect(cmd.browser).toBe(false);
+            expect(cmd.strategy).toBe('public');
+        }
+    });
+
+    it('requires --execute before create performs remote writes', async () => {
+        const cmd = getRegistry().get('confluence/create');
+        await expect(cmd.func({ space: '123', title: 'Doc', file: 'doc.md' })).rejects.toThrow(/--execute/);
+    });
+
+    it('creates a Cloud page from Markdown storage', async () => {
+        setCloudEnv();
+        await withTempMarkdown('# RCA\n\n- Payment failed', async (file) => {
+            const fetchMock = vi.fn(async (url, init) => {
+                expect(String(url)).toBe('https://team.atlassian.net/wiki/api/v2/pages');
+                const payload = JSON.parse(init.body);
+                expect(payload).toMatchObject({ spaceId: '987', title: 'PROJ-1 RCA' });
+                expect(payload.body.value).toContain('<h1>RCA</h1>');
+                expect(payload.body.value.replace(/\s*\n\s*/g, '')).toContain('<li>Payment failed</li>');
+                return jsonResponse({
+                    id: '555',
+                    title: 'PROJ-1 RCA',
+                    status: 'current',
+                    spaceId: '987',
+                    version: { number: 1, createdAt: '2026-05-01T00:00:00Z' },
+                    body: { storage: { value: '<h1>RCA</h1>' } },
+                    _links: { webui: '/spaces/ENG/pages/555' },
+                });
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const cmd = getRegistry().get('confluence/create');
+            const rows = await cmd.func({ space: '987', title: 'PROJ-1 RCA', file, representation: 'markdown', execute: true });
+            expect(rows[0]).toMatchObject({ status: 'created', id: '555', title: 'PROJ-1 RCA', version: 1 });
+            expect(rows[0].url).toBe('https://team.atlassian.net/wiki/spaces/ENG/pages/555');
+        });
+    });
+
+    it('updates a page by incrementing the current version', async () => {
+        setCloudEnv();
+        await withTempMarkdown('Updated body', async (file) => {
+            const fetchMock = vi.fn(async (url, init) => {
+                if (init.method === 'GET') {
+                    expect(String(url)).toBe('https://team.atlassian.net/wiki/api/v2/pages/555?body-format=storage');
+                    return jsonResponse({
+                        id: '555',
+                        title: 'Existing',
+                        status: 'current',
+                        version: { number: 7 },
+                        body: { storage: { value: '<p>Old</p>' } },
+                    });
+                }
+                expect(init.method).toBe('PUT');
+                const payload = JSON.parse(init.body);
+                expect(payload.version).toMatchObject({ number: 8, message: 'Sync from Jira' });
+                expect(payload.title).toBe('Existing');
+                return jsonResponse({
+                    id: '555',
+                    title: 'Existing',
+                    status: 'current',
+                    version: { number: 8 },
+                    body: { storage: { value: '<p>Updated body</p>' } },
+                });
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const cmd = getRegistry().get('confluence/update');
+            const rows = await cmd.func({ id: '555', file, representation: 'markdown', 'version-message': 'Sync from Jira', execute: true });
+            expect(rows[0]).toMatchObject({ status: 'updated', id: '555', version: 8 });
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+        });
+    });
+
+    it('does not update a Confluence page when the current version is malformed', async () => {
+        setCloudEnv();
+        await withTempMarkdown('Updated body', async (file) => {
+            const fetchMock = vi.fn(async (url, init) => {
+                expect(init.method).toBe('GET');
+                return jsonResponse({
+                    id: '555',
+                    title: 'Existing',
+                    status: 'current',
+                    body: { storage: { value: '<p>Old</p>' } },
+                });
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const cmd = getRegistry().get('confluence/update');
+            await expect(cmd.func({ id: '555', file, representation: 'markdown', execute: true }))
+                .rejects.toBeInstanceOf(CommandExecutionError);
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    it('searches with CQL scoped to a Data Center space', async () => {
+        clearEnv();
+        process.env.ATLASSIAN_CONFLUENCE_BASE_URL = 'https://conf.example.com/confluence';
+        process.env.ATLASSIAN_DEPLOYMENT = 'datacenter';
+        process.env.ATLASSIAN_PAT = 'pat';
+        const fetchMock = vi.fn(async (url) => {
+            const parsed = new URL(String(url));
+            expect(parsed.searchParams.get('cql')).toBe('space = "ENG" and (type = page)');
+            return jsonResponse({
+                results: [{
+                    content: {
+                        id: '123',
+                        type: 'page',
+                        status: 'current',
+                        title: 'Runbook',
+                        space: { key: 'ENG' },
+                        _links: { webui: '/display/ENG/Runbook' },
+                    },
+                    lastModified: '2026-05-02T00:00:00Z',
+                }],
+            });
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('confluence/search');
+        const rows = await cmd.func({ cql: 'type = page', space: 'ENG', limit: 10 });
+        expect(rows[0]).toMatchObject({ id: '123', title: 'Runbook', spaceKey: 'ENG' });
+        expect(rows[0].url).toBe('https://conf.example.com/confluence/display/ENG/Runbook');
+    });
+
+    it('separates Confluence search empty results from malformed search payloads', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('confluence/search');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ results: [] })));
+        await expect(cmd.func({ cql: 'type = page', limit: 10 })).rejects.toBeInstanceOf(EmptyResultError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ items: [] })));
+        await expect(cmd.func({ cql: 'type = page', limit: 10 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('fails typed when Confluence page payload lacks stable page identity', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ title: 'Missing id', version: { number: 1 } })));
+        const cmd = getRegistry().get('confluence/page');
+        await expect(cmd.func({ id: '555' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});