@jackwener/opencli 1.7.12 → 1.7.13

package/clis/toutiao/toutiao.test.js

@@ -0,0 +1,378 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+import {
+    HOT_BOARD_URL,
+    __test__,
+    mapHotRow,
+    looksToutiaoAuthWallText,
+    parseArticlesPage,
+    parseHotLimit,
+    parseToutiaoArticlesText,
+} from './utils.js';
+
+import './articles.js';
+import './hot.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('toutiao parseArticlesPage', () => {
+    it('falls back to default for empty / undefined / null', () => {
+        expect(parseArticlesPage(undefined)).toBe(1);
+        expect(parseArticlesPage(null)).toBe(1);
+        expect(parseArticlesPage('')).toBe(1);
+        expect(parseArticlesPage(undefined, 3)).toBe(3);
+    });
+
+    it('parses valid integer pages in [1, 4]', () => {
+        expect(parseArticlesPage(1)).toBe(1);
+        expect(parseArticlesPage('2')).toBe(2);
+        expect(parseArticlesPage(4)).toBe(4);
+    });
+
+    it('rejects non-integer pages with ArgumentError', () => {
+        expect(() => parseArticlesPage('abc')).toThrow(ArgumentError);
+        expect(() => parseArticlesPage(1.5)).toThrow(ArgumentError);
+    });
+
+    it('rejects out-of-range pages with ArgumentError (no silent clamp)', () => {
+        expect(() => parseArticlesPage(0)).toThrow(ArgumentError);
+        expect(() => parseArticlesPage(5)).toThrow(ArgumentError);
+        expect(() => parseArticlesPage(-1)).toThrow(ArgumentError);
+        expect(() => parseArticlesPage(99)).toThrow(ArgumentError);
+    });
+});
+
+describe('toutiao parseHotLimit', () => {
+    it('falls back to default for empty / undefined / null', () => {
+        expect(parseHotLimit(undefined)).toBe(30);
+        expect(parseHotLimit(null)).toBe(30);
+        expect(parseHotLimit('')).toBe(30);
+        expect(parseHotLimit(undefined, 10)).toBe(10);
+    });
+
+    it('parses valid integer limits in [1, 50]', () => {
+        expect(parseHotLimit(1)).toBe(1);
+        expect(parseHotLimit('30')).toBe(30);
+        expect(parseHotLimit(50)).toBe(50);
+    });
+
+    it('rejects out-of-range limits with ArgumentError (no silent clamp)', () => {
+        expect(() => parseHotLimit(0)).toThrow(ArgumentError);
+        expect(() => parseHotLimit(51)).toThrow(ArgumentError);
+        expect(() => parseHotLimit(-1)).toThrow(ArgumentError);
+        expect(() => parseHotLimit(1.5)).toThrow(ArgumentError);
+    });
+
+    it('rejects non-numeric limits with ArgumentError', () => {
+        expect(() => parseHotLimit('abc')).toThrow(ArgumentError);
+    });
+});
+
+describe('toutiao parseToutiaoArticlesText (silent column drop fix)', () => {
+    const rowWithStats = [
+        '短标题',
+        '04-20 20:30',
+        '已发布',
+        '展现 8 阅读 0 点赞 0 评论 0',
+    ].join('\n');
+
+    it('keeps short chinese titles and emits full row when stats present', () => {
+        expect(parseToutiaoArticlesText(rowWithStats)).toEqual([
+            {
+                title: '短标题',
+                date: '04-20 20:30',
+                status: '已发布',
+                '展现': '8',
+                '阅读': '0',
+                '点赞': '0',
+                '评论': '0',
+            },
+        ]);
+    });
+
+    it('still emits partial row with null stat columns when stats line failed to render', () => {
+        // Regression: previously `if (title && stats) push` silently dropped
+        // rows that had a title but where the stats span had not finished
+        // rendering, masking creator-backend slow-render bugs.
+        const partial = [
+            '部分行 (stats 慢渲染)',
+            '04-20 20:30',
+            '已发布',
+            // stats line absent on purpose
+        ].join('\n');
+        const out = parseToutiaoArticlesText(partial);
+        expect(out).toEqual([
+            {
+                title: '部分行 (stats 慢渲染)',
+                date: '04-20 20:30',
+                status: '已发布',
+                '展现': null,
+                '阅读': null,
+                '点赞': null,
+                '评论': null,
+            },
+        ]);
+    });
+
+    it('returns empty array for non-text input', () => {
+        expect(parseToutiaoArticlesText('')).toEqual([]);
+        expect(parseToutiaoArticlesText(null)).toEqual([]);
+        expect(parseToutiaoArticlesText(undefined)).toEqual([]);
+    });
+
+    it('handles multi-row input without losing rows', () => {
+        const text = [
+            '第一篇文章',
+            '04-20 20:30',
+            '已发布',
+            '展现 100 阅读 50 点赞 5 评论 1',
+            '',
+            '第二篇文章',
+            '04-21 09:15',
+            '已发布',
+            '展现 8 阅读 0 点赞 0 评论 0',
+        ].join('\n');
+        expect(parseToutiaoArticlesText(text)).toHaveLength(2);
+    });
+});
+
+describe('toutiao auth wall detection', () => {
+    it('recognizes creator-login/captcha pages', () => {
+        expect(looksToutiaoAuthWallText('账号登录 请登录 mp.toutiao.com/profile_v4/login')).toBe(true);
+        expect(looksToutiaoAuthWallText('安全验证 captcha')).toBe(true);
+        expect(looksToutiaoAuthWallText('短标题 04-20 20:30 已发布 展现 1 阅读 1')).toBe(false);
+    });
+});
+
+describe('toutiao mapHotRow', () => {
+    it('projects upstream item to stable 8-column shape', () => {
+        const upstream = {
+            ClusterId: 12345,
+            ClusterIdStr: '12345',
+            Title: '某热点新闻',
+            QueryWord: '某热点',
+            HotValue: '987654',
+            Label: '热',
+            Url: 'https://www.toutiao.com/trending/12345/',
+            Image: { url: 'https://p.image/x.jpg', url_list: ['https://p.image/x.jpg'] },
+        };
+        expect(mapHotRow(upstream, 0)).toEqual({
+            rank: 1,
+            group_id: '12345',
+            title: '某热点新闻',
+            query: '某热点',
+            hot_value: 987654,
+            label: '热',
+            url: 'https://www.toutiao.com/trending/12345/',
+            image_url: 'https://p.image/x.jpg',
+        });
+    });
+
+    it('falls back to ClusterId numeric when ClusterIdStr missing', () => {
+        const out = mapHotRow({ ClusterId: 7, Title: 'X' }, 5);
+        expect(out.group_id).toBe('7');
+        expect(out.rank).toBe(6);
+    });
+
+    it('falls back QueryWord → Title when query missing', () => {
+        const out = mapHotRow({ Title: '只有标题' }, 0);
+        expect(out.query).toBe('只有标题');
+    });
+
+    it('handles Image as url_list-only shape', () => {
+        const out = mapHotRow({
+            Title: 'Y',
+            Image: { url_list: ['https://list.image/y.png'] },
+        }, 0);
+        expect(out.image_url).toBe('https://list.image/y.png');
+    });
+
+    it('handles live Image.url_list entries shaped as objects', () => {
+        const out = mapHotRow({
+            Title: 'Y',
+            Image: { url_list: [{ url: 'https://list.image/y.png' }] },
+        }, 0);
+        expect(out.image_url).toBe('https://list.image/y.png');
+    });
+
+    it('returns null image when Image missing or all variants empty', () => {
+        expect(mapHotRow({ Title: 'Z' }, 0).image_url).toBeNull();
+        expect(mapHotRow({ Title: 'Z', Image: {} }, 0).image_url).toBeNull();
+        expect(mapHotRow({ Title: 'Z', Image: { url_list: [] } }, 0).image_url).toBeNull();
+    });
+
+    it('drops untitled rows (returns null) instead of emitting empty-title row', () => {
+        expect(mapHotRow({ Title: '', ClusterId: 1 }, 0)).toBeNull();
+        expect(mapHotRow({ Title: '   ', ClusterId: 1 }, 0)).toBeNull();
+        expect(mapHotRow(null, 0)).toBeNull();
+        expect(mapHotRow('not-an-object', 0)).toBeNull();
+    });
+
+    it('returns null hot_value for non-numeric HotValue (no silent 0 sentinel)', () => {
+        expect(mapHotRow({ Title: 'Q', HotValue: 'NaN' }, 0).hot_value).toBeNull();
+        expect(mapHotRow({ Title: 'Q', HotValue: '-1' }, 0).hot_value).toBeNull();
+    });
+});
+
+describe('toutiao registry shape', () => {
+    const articles = getRegistry().get('toutiao/articles');
+    const hot = getRegistry().get('toutiao/hot');
+
+    it('articles is registered as browser/cookie read adapter', () => {
+        expect(articles).toBeTruthy();
+        expect(articles.access).toBe('read');
+        expect(articles.browser).toBe(true);
+        expect(articles.columns).toEqual(['title', 'date', 'status', '展现', '阅读', '点赞', '评论']);
+    });
+
+    it('hot is registered as public non-browser read adapter', () => {
+        expect(hot).toBeTruthy();
+        expect(hot.access).toBe('read');
+        expect(hot.browser).toBe(false);
+        expect(hot.columns).toEqual(['rank', 'group_id', 'title', 'query', 'hot_value', 'label', 'url', 'image_url']);
+    });
+});
+
+describe('toutiao articles adapter (registry func)', () => {
+    const cmd = getRegistry().get('toutiao/articles');
+
+    it('rejects invalid page before browser navigation', async () => {
+        const page = { goto: vi.fn(), wait: vi.fn(), evaluate: vi.fn() };
+
+        await expect(cmd.func(page, { page: 0 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func(page, { page: 5 })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('throws AuthRequiredError when creator backend renders a login wall', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue('账号登录 请登录'),
+        };
+
+        await expect(cmd.func(page, { page: 1 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('wraps render failures as CommandExecutionError', async () => {
+        const page = {
+            goto: vi.fn().mockRejectedValue(new Error('browser down')),
+            wait: vi.fn(),
+            evaluate: vi.fn(),
+        };
+
+        await expect(cmd.func(page, { page: 1 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError when rendered article text has no rows', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue('没有文章'),
+        };
+
+        await expect(cmd.func(page, { page: 1 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+});
+
+describe('toutiao hot adapter (registry func)', () => {
+    const cmd = getRegistry().get('toutiao/hot');
+
+    it('rejects invalid limit before fetching (no silent clamp)', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func(null, { limit: 0 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func(null, { limit: 51 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func(null, { limit: 'abc' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('hits the public hot-board URL with default limit', async () => {
+        const fetchMock = vi.fn().mockImplementation(() => Promise.resolve(
+            new Response(JSON.stringify({
+                data: [
+                    { ClusterIdStr: '1', Title: 'A', HotValue: '100' },
+                    { ClusterIdStr: '2', Title: 'B', HotValue: '200' },
+                ],
+            }), { status: 200 }),
+        ));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const rows = await cmd.func(null, {});
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(fetchMock.mock.calls[0][0]).toBe(HOT_BOARD_URL);
+        expect(rows).toHaveLength(2);
+        expect(rows[0]).toMatchObject({ rank: 1, group_id: '1', title: 'A', hot_value: 100 });
+        expect(rows[1]).toMatchObject({ rank: 2, group_id: '2', title: 'B', hot_value: 200 });
+    });
+
+    it('throws CommandExecutionError on non-OK HTTP', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockImplementation(() => Promise.resolve(
+            new Response('', { status: 503 }),
+        )));
+
+        await expect(cmd.func(null, { limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError on malformed JSON', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockImplementation(() => Promise.resolve(
+            new Response('not-json{{{', { status: 200 }),
+        )));
+
+        await expect(cmd.func(null, { limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError on in-band error envelope', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockImplementation(() => Promise.resolve(
+            new Response(JSON.stringify({ status: 'error', message: 'rate limited' }), { status: 200 }),
+        )));
+
+        await expect(cmd.func(null, { limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when fetch rejects (no silent catch)', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockImplementation(() => Promise.reject(new Error('network down'))));
+
+        await expect(cmd.func(null, { limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError when upstream payload is empty', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockImplementation(() => Promise.resolve(
+            new Response(JSON.stringify({ data: [] }), { status: 200 }),
+        )));
+
+        await expect(cmd.func(null, { limit: 5 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('caps result rows at limit and dense-ranks (1..N) after filtering', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockImplementation(() => Promise.resolve(
+            new Response(JSON.stringify({
+                data: [
+                    { ClusterIdStr: '1', Title: 'kept' },
+                    { ClusterIdStr: '2', Title: '' }, // empty title → dropped
+                    { ClusterIdStr: '3', Title: 'also kept' },
+                    { ClusterIdStr: '4', Title: 'over-limit' },
+                ],
+            }), { status: 200 }),
+        )));
+
+        const rows = await cmd.func(null, { limit: 2 });
+        expect(rows.map(r => r.title)).toEqual(['kept', 'also kept']);
+        expect(rows.map(r => r.rank)).toEqual([1, 2]); // dense rank after empty-title drop
+    });
+});
+
+describe('toutiao __test__ contract', () => {
+    it('exports min/max bounds for documentation parity', () => {
+        expect(__test__.ARTICLES_MIN_PAGE).toBe(1);
+        expect(__test__.ARTICLES_MAX_PAGE).toBe(4);
+        expect(__test__.HOT_MIN_LIMIT).toBe(1);
+        expect(__test__.HOT_MAX_LIMIT).toBe(50);
+    });
+});

package/clis/toutiao/utils.js

@@ -0,0 +1,161 @@
+/**
+ * Shared helpers for the toutiao adapter.
+ */
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+const ARTICLES_MIN_PAGE = 1;
+const ARTICLES_MAX_PAGE = 4;
+const HOT_MIN_LIMIT = 1;
+const HOT_MAX_LIMIT = 50;
+
+export function parseArticlesPage(raw, fallback = 1) {
+    if (raw === undefined || raw === null || raw === '') return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+        throw new ArgumentError(`--page must be an integer between ${ARTICLES_MIN_PAGE} and ${ARTICLES_MAX_PAGE}, got ${JSON.stringify(raw)}`);
+    }
+    if (parsed < ARTICLES_MIN_PAGE || parsed > ARTICLES_MAX_PAGE) {
+        throw new ArgumentError(`--page must be between ${ARTICLES_MIN_PAGE} and ${ARTICLES_MAX_PAGE}, got ${parsed}`);
+    }
+    return parsed;
+}
+
+export function parseHotLimit(raw, fallback = 30) {
+    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 ${HOT_MIN_LIMIT} and ${HOT_MAX_LIMIT}, got ${JSON.stringify(raw)}`);
+    }
+    if (parsed < HOT_MIN_LIMIT || parsed > HOT_MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be between ${HOT_MIN_LIMIT} and ${HOT_MAX_LIMIT}, got ${parsed}`);
+    }
+    return parsed;
+}
+
+const NON_TITLE_LINES = new Set([
+    '展现', '阅读', '点赞', '评论',
+    '查看数据', '查看评论', '修改', '更多', '首发',
+    '已发布', '定时发布', '定时发布中', '由文章生成', '审核中',
+]);
+
+const STATS_RE = /展现\s*([\d,]+)\s*阅读\s*([\d,]+)\s*点赞\s*([\d,]+)\s*评论\s*([\d,]*)/;
+
+/**
+ * Extract creator-backend article rows from the rendered text dump.
+ *
+ * Surfaces every row anchored on a `MM-DD HH:MM` line; if the matching stats
+ * line never came through (slow render / missing element), the row is still
+ * emitted with `null` for stat columns rather than silently dropped.
+ */
+export function parseToutiaoArticlesText(text) {
+    const lines = String(text || '').split('\n').map((line) => line.trim()).filter(Boolean);
+    const results = [];
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!/^\d{2}-\d{2}\s+\d{2}:\d{2}$/.test(line)) continue;
+
+        const date = line;
+        let title = null;
+        let status = null;
+        let stats = null;
+
+        for (let back = 3; back >= 1; back--) {
+            const prev = lines[i - back] || '';
+            if (!prev || prev.length >= 100 || /^\d+$/.test(prev) || NON_TITLE_LINES.has(prev)) continue;
+            title = prev;
+            break;
+        }
+
+        for (let fwd = 1; fwd < 8; fwd++) {
+            const fwdLine = lines[i + fwd] || '';
+            if (fwdLine === '已发布' || fwdLine === '定时发布中' || fwdLine === '审核中' || fwdLine === '由文章生成') {
+                status = fwdLine;
+            }
+            if (fwdLine.includes('展现') && fwdLine.includes('阅读')) {
+                const match = fwdLine.match(STATS_RE);
+                if (match) {
+                    stats = {
+                        '展现': match[1],
+                        '阅读': match[2],
+                        '点赞': match[3],
+                        '评论': match[4] || '0',
+                    };
+                }
+            }
+        }
+
+        if (!title) continue;
+
+        if (stats) {
+            results.push({ title, date, status, ...stats });
+        } else {
+            // Surface partial rows so callers can see they exist (was previously
+            // silently dropped — masking creator-backend slow-render bugs).
+            results.push({
+                title,
+                date,
+                status,
+                '展现': null,
+                '阅读': null,
+                '点赞': null,
+                '评论': null,
+            });
+        }
+    }
+
+    return results;
+}
+
+function trimOrNull(v) {
+    const s = String(v ?? '').trim();
+    return s ? s : null;
+}
+
+function pickImage(item) {
+    const url = item?.Image?.url;
+    if (typeof url === 'string' && url) return url;
+    const firstFromList = Array.isArray(item?.Image?.url_list)
+        ? item.Image.url_list
+            .map((entry) => typeof entry === 'string' ? entry : entry?.url)
+            .find((u) => typeof u === 'string' && u)
+        : null;
+    return firstFromList || null;
+}
+
+function parseHot(v) {
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/**
+ * Project a row from the public toutiao hot-board API into stable shape.
+ */
+export function mapHotRow(item, index) {
+    if (!item || typeof item !== 'object') return null;
+    const groupId = trimOrNull(item.ClusterIdStr || (item.ClusterId != null ? String(item.ClusterId) : null));
+    const title = trimOrNull(item.Title);
+    if (!title) return null;
+    return {
+        rank: index + 1,
+        group_id: groupId,
+        title,
+        query: trimOrNull(item.QueryWord) || title,
+        hot_value: parseHot(item.HotValue),
+        label: trimOrNull(item.Label),
+        url: trimOrNull(item.Url),
+        image_url: pickImage(item),
+    };
+}
+
+export const HOT_BOARD_URL = 'https://www.toutiao.com/hot-event/hot-board/?origin=toutiao_pc';
+
+export function looksToutiaoAuthWallText(value) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!text) return false;
+    return /登录|请登录|账号登录|扫码登录|安全验证|验证码|captcha/.test(text) ||
+        /\b(login|sign in|captcha|verification required)\b/.test(text) ||
+        /mp\.toutiao\.com\/profile_v4\/login/.test(text);
+}
+
+export const __test__ = { ARTICLES_MIN_PAGE, ARTICLES_MAX_PAGE, HOT_MIN_LIMIT, HOT_MAX_LIMIT };

package/clis/tvmaze/search.js

@@ -0,0 +1,61 @@
+// tvmaze search — TV show search by title.
+//
+// Hits `https://api.tvmaze.com/search/shows?q=<query>` and returns one row per
+// match. Includes the show id (round-tripable into `tvmaze show <id>`),
+// premiered/ended dates, network, and TVmaze rating so agents can rank.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    TVMAZE_BASE, joinList, requireBoundedInt, requireString, stripHtml, tvmazeFetch,
+} from './utils.js';
+
+cli({
+    site: 'tvmaze',
+    name: 'search',
+    access: 'read',
+    description: 'TVmaze TV show search by title (returns id, name, network, premiered/ended, rating)',
+    domain: 'tvmaze.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, type: 'string', required: true, help: 'TV show title or fragment to search for' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max rows to return (1-50)' },
+    ],
+    columns: [
+        'rank', 'id', 'name', 'type', 'language', 'genres',
+        'status', 'premiered', 'ended', 'network', 'rating',
+        'matchScore', 'summary', 'url',
+    ],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 20, 50, 'limit');
+        const list = await tvmazeFetch(
+            `${TVMAZE_BASE}/search/shows?q=${encodeURIComponent(query)}`,
+            `tvmaze search ${query}`,
+        );
+        if (!Array.isArray(list) || list.length === 0) {
+            throw new EmptyResultError('tvmaze search', `TVmaze returned no shows matching "${query}".`);
+        }
+        const rows = list.slice(0, limit).map((entry, i) => {
+            const show = entry?.show ?? {};
+            const network = show.network?.name ?? show.webChannel?.name ?? '';
+            return {
+                rank: i + 1,
+                id: typeof show.id === 'number' ? show.id : null,
+                name: String(show.name ?? '').trim(),
+                type: String(show.type ?? '').trim(),
+                language: String(show.language ?? '').trim(),
+                genres: joinList(show.genres),
+                status: String(show.status ?? '').trim(),
+                premiered: typeof show.premiered === 'string' ? show.premiered : null,
+                ended: typeof show.ended === 'string' ? show.ended : null,
+                network: String(network).trim(),
+                rating: show.rating?.average == null ? null : Number(show.rating.average),
+                matchScore: typeof entry?.score === 'number' ? entry.score : null,
+                summary: stripHtml(show.summary),
+                url: String(show.url ?? '').trim(),
+            };
+        });
+        return rows;
+    },
+});

package/clis/tvmaze/show.js

@@ -0,0 +1,60 @@
+// tvmaze show — full TV show details by TVmaze id.
+//
+// Hits `https://api.tvmaze.com/shows/<id>`. Returns one row with name, status,
+// premiered/ended dates, network, runtime, rating, official site, IMDB / TheTVDB
+// cross-refs (so agents can hop into other adapters), and a plain-text summary.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { TVMAZE_BASE, joinList, requireShowId, stripHtml, tvmazeFetch } from './utils.js';
+
+cli({
+    site: 'tvmaze',
+    name: 'show',
+    access: 'read',
+    description: 'Single TVmaze TV show detail by id (network, schedule, rating, IMDB/TheTVDB cross-refs)',
+    domain: 'tvmaze.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, type: 'int', required: true, help: 'TVmaze show id (positive integer)' },
+    ],
+    columns: [
+        'id', 'name', 'type', 'language', 'genres', 'status',
+        'premiered', 'ended', 'runtime', 'averageRuntime', 'network',
+        'country', 'schedule', 'rating', 'imdb', 'thetvdb',
+        'officialSite', 'summary', 'url',
+    ],
+    func: async (args) => {
+        const id = requireShowId(args.id);
+        const show = await tvmazeFetch(`${TVMAZE_BASE}/shows/${id}`, `tvmaze show ${id}`);
+        if (!show || show.id == null) {
+            throw new EmptyResultError('tvmaze show', `TVmaze returned no show for id ${id}.`);
+        }
+        const network = show.network?.name ?? show.webChannel?.name ?? '';
+        const country = show.network?.country?.name ?? show.webChannel?.country?.name ?? '';
+        const days = Array.isArray(show.schedule?.days) ? show.schedule.days.join(', ') : '';
+        const time = String(show.schedule?.time ?? '').trim();
+        const schedule = days || time ? `${days}${days && time ? ' ' : ''}${time}`.trim() : '';
+        return [{
+            id: Number(show.id),
+            name: String(show.name ?? '').trim(),
+            type: String(show.type ?? '').trim(),
+            language: String(show.language ?? '').trim(),
+            genres: joinList(show.genres),
+            status: String(show.status ?? '').trim(),
+            premiered: typeof show.premiered === 'string' ? show.premiered : null,
+            ended: typeof show.ended === 'string' ? show.ended : null,
+            runtime: show.runtime == null ? null : Number(show.runtime),
+            averageRuntime: show.averageRuntime == null ? null : Number(show.averageRuntime),
+            network: String(network).trim(),
+            country: String(country).trim(),
+            schedule,
+            rating: show.rating?.average == null ? null : Number(show.rating.average),
+            imdb: String(show.externals?.imdb ?? '').trim(),
+            thetvdb: show.externals?.thetvdb == null ? null : Number(show.externals.thetvdb),
+            officialSite: String(show.officialSite ?? '').trim(),
+            summary: stripHtml(show.summary),
+            url: String(show.url ?? '').trim(),
+        }];
+    },
+});