@jackwener/opencli 1.8.0 → 1.8.1

package/clis/confluence/create.js

@@ -0,0 +1,39 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { requireExecute, requirePayloadObject, requireString } from '../_atlassian/shared.js';
+import { confluenceConfig, createPagePayload, normalizeConfluencePage, readPageBodyFile } from './shared.js';
+import { atlassianRequest } from '../_atlassian/shared.js';
+
+cli({
+    site: 'confluence',
+    name: 'create',
+    access: 'write',
+    description: 'Create a Confluence page from Markdown or storage XHTML',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'space', type: 'string', required: true, help: 'Cloud space id, or Data Center space key' },
+        { name: 'title', type: 'string', required: true, help: 'Page title' },
+        { name: 'file', type: 'string', required: true, help: 'Markdown file path' },
+        { name: 'parent', type: 'string', help: 'Optional parent page id' },
+        { name: 'representation', type: 'string', default: 'markdown', choices: ['markdown', 'storage'], help: 'Input file format' },
+        { name: 'execute', type: 'boolean', help: 'Actually create the remote page' },
+    ],
+    columns: ['status', 'id', 'title', 'spaceId', 'spaceKey', 'version', 'url'],
+    func: async (args) => {
+        requireExecute(args, 'confluence create');
+        requireString(args.space, 'Confluence space');
+        requireString(args.title, 'Confluence page title');
+        const storage = await readPageBodyFile(args);
+        const config = confluenceConfig();
+        const payload = createPagePayload(config, args, storage);
+        const path = config.deployment === 'cloud' ? '/api/v2/pages' : '/rest/api/content';
+        const page = requirePayloadObject(await atlassianRequest(config, path, {
+            method: 'POST',
+            body: payload,
+            label: 'confluence create',
+        }), 'confluence create');
+        const normalized = normalizeConfluencePage(page, config);
+        return [{ ...normalized, pageStatus: normalized.status, status: 'created' }];
+    },
+});

package/clis/confluence/page.js

@@ -0,0 +1,23 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { requireString } from '../_atlassian/shared.js';
+import { confluenceConfig, getPage, normalizeConfluencePage } from './shared.js';
+
+cli({
+    site: 'confluence',
+    name: 'page',
+    access: 'read',
+    description: 'Confluence page by id with storage and Markdown body',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Confluence page id' },
+    ],
+    columns: ['id', 'title', 'status', 'spaceId', 'spaceKey', 'version', 'url'],
+    func: async (args) => {
+        const config = confluenceConfig();
+        const id = requireString(args.id, 'Confluence page id');
+        const page = await getPage(config, id);
+        return [normalizeConfluencePage(page, config)];
+    },
+});

package/clis/confluence/search.js

@@ -0,0 +1,34 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { atlassianRequest, parseLimit, queryString, requireNonEmptyRows, requireString } from '../_atlassian/shared.js';
+import { confluenceConfig, confluenceResults, normalizeSearchResult, withSpaceCql } from './shared.js';
+
+cli({
+    site: 'confluence',
+    name: 'search',
+    access: 'read',
+    description: 'Search Confluence content with CQL',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'cql', positional: true, required: true, help: 'CQL query, e.g. "type = page and title ~ \\"RCA\\""' },
+        { name: 'space', type: 'string', help: 'Limit search to a Confluence space key' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max results to return (1-100)' },
+    ],
+    columns: ['id', 'title', 'type', 'spaceKey', 'status', 'lastModified', 'url'],
+    func: async (args) => {
+        const config = confluenceConfig();
+        const cql = withSpaceCql(requireString(args.cql, 'CQL'), args.space);
+        const limit = parseLimit(args.limit, 20, 100, 'confluence limit');
+        // CQL search is still exposed through Confluence REST v1 for Cloud;
+        // page CRUD uses v2 where available.
+        const path = `/rest/api/search${queryString({ cql, limit })}`;
+        const data = await atlassianRequest(config, path, { label: 'confluence search' });
+        const results = confluenceResults(data, 'confluence search');
+        return requireNonEmptyRows(
+            results.map((result) => normalizeSearchResult(result, config)),
+            'confluence search',
+            `No Confluence content matched "${cql}".`,
+        );
+    },
+});

package/clis/confluence/shared.js

@@ -0,0 +1,173 @@
+import {
+    atlassianRequest,
+    getConfluenceConfig,
+    htmlToMarkdown,
+    markdownToConfluenceStorage,
+    queryString,
+    requirePayloadArray,
+    requirePayloadObject,
+    requirePayloadString,
+    readUtf8File,
+    requireString,
+} from '../_atlassian/shared.js';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+
+export function confluenceConfig() {
+    return getConfluenceConfig();
+}
+
+function confluenceUrl(config, link) {
+    if (!link) return '';
+    if (/^https?:\/\//i.test(link)) return link;
+    return `${config.baseUrl}${link.startsWith('/') ? link : `/${link}`}`;
+}
+
+function pageStorageBody(page) {
+    return page?.body?.storage?.value
+        ?? page?.body?.view?.value
+        ?? '';
+}
+
+export function normalizeConfluencePage(page, config) {
+    const row = requirePayloadObject(page, 'confluence page');
+    const id = requirePayloadString(row.id, 'page id', 'confluence page');
+    const title = requirePayloadString(row.title, 'title', 'confluence page');
+    const storage = pageStorageBody(row);
+    const version = row.version?.number != null ? Number(row.version.number) : undefined;
+    const links = row._links && typeof row._links === 'object' && !Array.isArray(row._links) ? row._links : {};
+    const webui = links.webui ?? links.tinyui ?? '';
+    return {
+        id,
+        title,
+        status: String(row.status ?? ''),
+        spaceId: row.spaceId != null ? String(row.spaceId) : undefined,
+        spaceKey: row.space?.key ? String(row.space.key) : undefined,
+        parentId: row.parentId != null ? String(row.parentId) : undefined,
+        version,
+        createdAt: row.createdAt ? String(row.createdAt) : undefined,
+        updatedAt: row.version?.createdAt ?? row.version?.when ?? undefined,
+        url: confluenceUrl(config, webui),
+        body: {
+            storage,
+            markdown: htmlToMarkdown(storage),
+        },
+    };
+}
+
+export async function getPage(config, pageId) {
+    if (config.deployment === 'cloud') {
+        const page = await atlassianRequest(config, `/api/v2/pages/${encodeURIComponent(pageId)}${queryString({ 'body-format': 'storage' })}`, {
+            label: `confluence page ${pageId}`,
+        });
+        return requirePayloadObject(page, `confluence page ${pageId}`);
+    }
+    const page = await atlassianRequest(config, `/rest/api/content/${encodeURIComponent(pageId)}${queryString({ expand: 'body.storage,version,space,ancestors' })}`, {
+        label: `confluence page ${pageId}`,
+    });
+    return requirePayloadObject(page, `confluence page ${pageId}`);
+}
+
+export async function readPageBodyFile(args) {
+    const text = await readUtf8File(args.file);
+    if (args.representation === 'storage') return text;
+    return markdownToConfluenceStorage(text);
+}
+
+export function createPagePayload(config, args, storage) {
+    const title = requireString(args.title, 'Confluence page title');
+    const space = requireString(args.space, 'Confluence space');
+    if (config.deployment === 'cloud') {
+        return {
+            spaceId: space,
+            status: 'current',
+            title,
+            ...(args.parent ? { parentId: String(args.parent) } : {}),
+            body: { representation: 'storage', value: storage },
+        };
+    }
+    return {
+        type: 'page',
+        status: 'current',
+        title,
+        space: { key: space },
+        ...(args.parent ? { ancestors: [{ id: String(args.parent) }] } : {}),
+        body: { storage: { representation: 'storage', value: storage } },
+    };
+}
+
+export function updatePagePayload(config, current, args, storage) {
+    const page = requirePayloadObject(current, 'confluence current page');
+    const id = requirePayloadString(page.id, 'page id', 'confluence current page');
+    const title = args.title ? requireString(args.title, 'Confluence page title') : requirePayloadString(page.title, 'title', 'confluence current page');
+    const currentVersion = Number(page.version?.number);
+    if (!Number.isSafeInteger(currentVersion) || currentVersion < 1) {
+        throw new CommandExecutionError('confluence update could not determine the current page version.');
+    }
+    const nextVersion = currentVersion + 1;
+    if (config.deployment === 'cloud') {
+        return {
+            id,
+            status: 'current',
+            title,
+            body: { representation: 'storage', value: storage },
+            version: {
+                number: nextVersion,
+                ...(args['version-message'] ? { message: String(args['version-message']) } : {}),
+            },
+        };
+    }
+    return {
+        id,
+        type: 'page',
+        status: 'current',
+        title,
+        body: { storage: { representation: 'storage', value: storage } },
+        version: {
+            number: nextVersion,
+            ...(args['version-message'] ? { message: String(args['version-message']) } : {}),
+        },
+    };
+}
+
+export function normalizeSearchResult(result, config) {
+    const row = requirePayloadObject(result, 'confluence search result');
+    const content = row.content ?? row;
+    const contentObject = requirePayloadObject(content, 'confluence search result content');
+    const id = requirePayloadString(contentObject.id, 'content id', 'confluence search result');
+    const title = requirePayloadString(row.title ?? contentObject.title, 'title', 'confluence search result');
+    const space = row.space ?? contentObject.space ?? {};
+    return {
+        id,
+        title,
+        type: String(contentObject.type ?? row.entityType ?? ''),
+        spaceKey: String(space?.key ?? ''),
+        status: String(contentObject.status ?? ''),
+        lastModified: String(row.lastModified ?? contentObject.version?.when ?? contentObject.version?.createdAt ?? ''),
+        url: confluenceUrl(config, row.url ?? contentObject._links?.webui ?? ''),
+        excerpt: row.excerpt ? htmlToMarkdown(row.excerpt) : '',
+    };
+}
+
+export function confluenceResults(data, label) {
+    const payload = requirePayloadObject(data, label);
+    return requirePayloadArray(payload.results, label);
+}
+
+export function withSpaceCql(cql, space) {
+    const q = String(cql ?? '').trim();
+    const s = String(space ?? '').trim();
+    if (!s) return q;
+    const escaped = s.replace(/"/g, '\\"');
+    if (!q) return `space = "${escaped}"`;
+    return `space = "${escaped}" and (${q})`;
+}
+
+export const __test__ = {
+    createPagePayload,
+    getPage,
+    normalizeConfluencePage,
+    normalizeSearchResult,
+    readPageBodyFile,
+    updatePagePayload,
+    withSpaceCql,
+};

package/clis/confluence/update.js

@@ -0,0 +1,38 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { atlassianRequest, requireExecute, requirePayloadObject, requireString } from '../_atlassian/shared.js';
+import { confluenceConfig, getPage, normalizeConfluencePage, readPageBodyFile, updatePagePayload } from './shared.js';
+
+cli({
+    site: 'confluence',
+    name: 'update',
+    access: 'write',
+    description: 'Update a Confluence page body from Markdown or storage XHTML',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Confluence page id' },
+        { name: 'file', type: 'string', required: true, help: 'Markdown file path' },
+        { name: 'title', type: 'string', help: 'Optional replacement title; defaults to current title' },
+        { name: 'version-message', type: 'string', help: 'Confluence version message' },
+        { name: 'representation', type: 'string', default: 'markdown', choices: ['markdown', 'storage'], help: 'Input file format' },
+        { name: 'execute', type: 'boolean', help: 'Actually update the remote page' },
+    ],
+    columns: ['status', 'id', 'title', 'spaceId', 'spaceKey', 'version', 'url'],
+    func: async (args) => {
+        requireExecute(args, 'confluence update');
+        const config = confluenceConfig();
+        const id = requireString(args.id, 'Confluence page id');
+        const current = await getPage(config, id);
+        const storage = await readPageBodyFile(args);
+        const payload = updatePagePayload(config, current, args, storage);
+        const path = config.deployment === 'cloud' ? `/api/v2/pages/${encodeURIComponent(id)}` : `/rest/api/content/${encodeURIComponent(id)}`;
+        const page = requirePayloadObject(await atlassianRequest(config, path, {
+            method: 'PUT',
+            body: payload,
+            label: `confluence update ${id}`,
+        }), `confluence update ${id}`);
+        const normalized = normalizeConfluencePage(page, config);
+        return [{ ...normalized, pageStatus: normalized.status, status: 'updated' }];
+    },
+});

package/clis/douyin/hashtag.js

@@ -1,6 +1,40 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { browserFetch } from './_shared/browser-fetch.js';
-import { ArgumentError } from '@jackwener/opencli/errors';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireListField(res, field, action) {
+    if (!isPlainObject(res)) {
+        throw new CommandExecutionError(`douyin hashtag ${action}: API returned malformed payload`);
+    }
+    const list = res[field];
+    if (list === undefined || list === null) return [];
+    if (!Array.isArray(list)) {
+        throw new CommandExecutionError(`douyin hashtag ${action}: API returned malformed "${field}"`);
+    }
+    return list;
+}
+
+function validateHashtagArgs(kwargs) {
+    const action = kwargs.action;
+    if (action === 'search') {
+        const keyword = String(kwargs.keyword ?? '').trim();
+        if (!keyword) {
+            throw new ArgumentError('douyin hashtag search 需要 --keyword <关键词>', '示例: opencli douyin hashtag search --keyword 美食');
+        }
+        return;
+    }
+    if (action === 'suggest') {
+        const cover = String(kwargs.cover ?? '').trim();
+        if (!cover) {
+            throw new ArgumentError('douyin hashtag suggest 需要 --cover <cover_uri>', 'suggest 基于已上传的视频封面做 AI 推荐, 不是关键词搜索. 关键词搜索请用 `douyin hashtag search --keyword <词>`.');
+        }
+    }
+}
+
 cli({
     site: 'douyin',
     name: 'hashtag',
@@ -9,43 +43,70 @@ cli({
     domain: 'creator.douyin.com',
     strategy: Strategy.COOKIE,
     args: [
-        { name: 'action', required: true, positional: true, choices: ['search', 'suggest', 'hot'], help: 'search=关键词搜索 suggest=AI推荐 hot=热点词' },
-        { name: 'keyword', default: '', help: '搜索关键词（search/hot 使用）' },
-        { name: 'cover', default: '', help: '封面 URI（suggest 使用）' },
+        { name: 'action', required: true, positional: true, choices: ['search', 'suggest', 'hot'], help: 'search=关键词搜索 (--keyword 必填), suggest=AI推荐 (--cover 必填), hot=热点词 (--keyword 可选)' },
+        { name: 'keyword', default: '', help: '搜索关键词. search 必填; hot 可选; suggest 不使用 (传 --cover)' },
+        { name: 'cover', default: '', help: '封面 URI (cover_uri). suggest 必填; 其它 action 不使用' },
         { name: 'limit', type: 'int', default: 10 },
     ],
     columns: ['name', 'id', 'view_count'],
+    validateArgs: validateHashtagArgs,
     func: async (page, kwargs) => {
+        validateHashtagArgs(kwargs);
         const action = kwargs.action;
         if (action === 'search') {
-            const url = `https://creator.douyin.com/aweme/v1/challenge/search/?keyword=${encodeURIComponent(kwargs.keyword)}&count=${kwargs.limit}&aid=1128`;
+            const keyword = String(kwargs.keyword ?? '').trim();
+            const url = `https://creator.douyin.com/aweme/v1/challenge/search/?keyword=${encodeURIComponent(keyword)}&count=${kwargs.limit}&aid=1128`;
             const res = await browserFetch(page, 'GET', url);
-            return (res.challenge_list ?? []).map(c => ({
-                name: c.challenge_info.cha_name,
-                id: c.challenge_info.cid,
-                view_count: c.challenge_info.view_count,
-            }));
+            const list = requireListField(res, 'challenge_list', 'search');
+            const rows = list.flatMap(c => {
+                const info = c?.challenge_info;
+                if (!isPlainObject(info)) return [];
+                return [{
+                    name: info.cha_name,
+                    id: info.cid,
+                    view_count: info.view_count,
+                }];
+            });
+            if (list.length > 0 && rows.length === 0) {
+                throw new CommandExecutionError('douyin hashtag search: API returned challenges but none had stable challenge_info shape');
+            }
+            return rows;
         }
         if (action === 'suggest') {
-            const url = `https://creator.douyin.com/web/api/media/hashtag/rec/?cover_uri=${encodeURIComponent(kwargs.cover)}&aid=1128`;
+            const cover = String(kwargs.cover ?? '').trim();
+            const url = `https://creator.douyin.com/web/api/media/hashtag/rec/?cover_uri=${encodeURIComponent(cover)}&aid=1128`;
             const res = await browserFetch(page, 'GET', url);
-            return (res.hashtag_list ?? []).map(h => ({ name: h.name, id: h.id, view_count: h.view_count }));
+            const list = requireListField(res, 'hashtag_list', 'suggest');
+            return list.map(h => ({ name: h?.name ?? '', id: h?.id ?? '', view_count: h?.view_count ?? 0 }));
         }
         if (action === 'hot') {
-            const kw = kwargs.keyword;
+            const kw = String(kwargs.keyword ?? '').trim();
             const url = `https://creator.douyin.com/aweme/v1/hotspot/recommend/?${kw ? `keyword=${encodeURIComponent(kw)}&` : ''}aid=1128`;
             const res = await browserFetch(page, 'GET', url);
-            const items = res.hotspot_list
-                ?? res.all_sentences?.map(h => ({
-                    sentence: h.word ?? '',
-                    hot_value: h.hot_value,
-                    sentence_id: h.sentence_id ?? '',
-                }))
-                ?? [];
+            if (!isPlainObject(res)) {
+                throw new CommandExecutionError('douyin hashtag hot: API returned malformed payload');
+            }
+            const hotspotList = res.hotspot_list;
+            const allSentences = res.all_sentences;
+            if (hotspotList !== undefined && hotspotList !== null && !Array.isArray(hotspotList)) {
+                throw new CommandExecutionError('douyin hashtag hot: API returned malformed "hotspot_list"');
+            }
+            if (allSentences !== undefined && allSentences !== null && !Array.isArray(allSentences)) {
+                throw new CommandExecutionError('douyin hashtag hot: API returned malformed "all_sentences"');
+            }
+            const items = Array.isArray(hotspotList)
+                ? hotspotList
+                : Array.isArray(allSentences)
+                    ? allSentences.map(h => ({
+                        sentence: h?.word ?? '',
+                        hot_value: h?.hot_value,
+                        sentence_id: h?.sentence_id ?? '',
+                    }))
+                    : [];
             return items.slice(0, kwargs.limit).map(h => ({
-                name: h.sentence,
-                id: 'sentence_id' in h ? h.sentence_id : '',
-                view_count: h.hot_value,
+                name: h?.sentence ?? '',
+                id: h && 'sentence_id' in h ? h.sentence_id : '',
+                view_count: h?.hot_value ?? 0,
             }));
         }
         throw new ArgumentError(`未知的 action: ${action}`);

package/clis/douyin/hashtag.test.js

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
 const { browserFetchMock } = vi.hoisted(() => ({
     browserFetchMock: vi.fn(),
 }));
@@ -31,6 +32,118 @@ describe('douyin hashtag', () => {
         const cmd = [...registry.values()].find(c => c.site === 'douyin' && c.name === 'hashtag');
         expect(cmd?.strategy).toBe('cookie');
     });
+    it('registers action-specific validation so missing args fail before browser pre-navigation', () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        expect(cmd?.validateArgs).toBeTypeOf('function');
+        expect(() => cmd.validateArgs({ action: 'search', keyword: '', cover: '', limit: 10 }))
+            .toThrow(ArgumentError);
+        expect(() => cmd.validateArgs({ action: 'suggest', keyword: '速效救心丸', cover: '', limit: 10 }))
+            .toThrow(ArgumentError);
+        expect(() => cmd.validateArgs({ action: 'hot', keyword: '', cover: '', limit: 10 }))
+            .not.toThrow();
+        expect(browserFetchMock).not.toHaveBeenCalled();
+    });
+
+    it('search throws ArgumentError when --keyword is missing or blank (#1689)', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        await expect(cmd.func({}, { action: 'search', keyword: '', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func({}, { action: 'search', keyword: '   ', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        expect(browserFetchMock).not.toHaveBeenCalled();
+    });
+
+    it('suggest throws ArgumentError when --cover is missing (#1689 root cause)', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        await expect(cmd.func({}, { action: 'suggest', keyword: '速效救心丸', cover: '', limit: 10 }))
+            .rejects.toMatchObject({ code: 'ARGUMENT', message: expect.stringContaining('--cover') });
+        await expect(cmd.func({}, { action: 'suggest', keyword: '', cover: '   ', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        expect(browserFetchMock).not.toHaveBeenCalled();
+    });
+
+    it('hot accepts empty --keyword (it is optional for hot)', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ hotspot_list: [{ sentence: '热点1', hot_value: 100, sentence_id: 'h1' }] });
+        const rows = await cmd.func({}, { action: 'hot', keyword: '', cover: '', limit: 5 });
+        expect(rows[0]).toEqual({ name: '热点1', id: 'h1', view_count: 100 });
+        const url = browserFetchMock.mock.calls[0][2];
+        expect(url).not.toContain('keyword=');
+    });
+
+    it('search threads --keyword + count into the challenge/search URL', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({
+            challenge_list: [{ challenge_info: { cha_name: '美食', cid: '123', view_count: 5000 } }],
+        });
+        const rows = await cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 });
+        expect(rows).toEqual([{ name: '美食', id: '123', view_count: 5000 }]);
+        const url = browserFetchMock.mock.calls[0][2];
+        expect(url).toContain('challenge/search');
+        expect(url).toContain('keyword=' + encodeURIComponent('美食'));
+        expect(url).toContain('count=10');
+    });
+
+    it('suggest threads --cover into the hashtag/rec URL on success', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({
+            hashtag_list: [{ name: '推荐话题', id: 'h99', view_count: 1234 }],
+        });
+        const rows = await cmd.func({}, { action: 'suggest', keyword: '', cover: 'tos-cn-i-cover/abc', limit: 10 });
+        expect(rows).toEqual([{ name: '推荐话题', id: 'h99', view_count: 1234 }]);
+        const url = browserFetchMock.mock.calls[0][2];
+        expect(url).toContain('hashtag/rec');
+        expect(url).toContain('cover_uri=' + encodeURIComponent('tos-cn-i-cover/abc'));
+    });
+
+    it('search throws CommandExecutionError when API returns a non-object payload', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce(null);
+        await expect(cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('search throws CommandExecutionError when challenge_list has wrong shape', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ challenge_list: 'not-an-array' });
+        await expect(cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('search throws CommandExecutionError when challenges return but none parse', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({
+            challenge_list: [{ challenge_info: null }, { other_field: 1 }],
+        });
+        await expect(cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('suggest throws CommandExecutionError when hashtag_list has wrong shape', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ hashtag_list: 'oops' });
+        await expect(cmd.func({}, { action: 'suggest', keyword: '', cover: 'tos-cn-i-cover/x', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('hot throws CommandExecutionError when hotspot_list has wrong shape', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ hotspot_list: { malformed: true } });
+        await expect(cmd.func({}, { action: 'hot', keyword: '', cover: '', limit: 5 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
     it('parses the current hotspot recommendation shape', async () => {
         const registry = getRegistry();
         const command = [...registry.values()].find((cmd) => cmd.site === 'douyin' && cmd.name === 'hashtag');

package/clis/geogebra/add-circle.js

@@ -0,0 +1,46 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbEval, normalizeLabel, normalizeNumber, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'add-circle',
+  access: 'write',
+  description: 'Create a circle by center+radius or center+point',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra add-circle --center A --radius 3',
+  args: [
+    { name: 'center', required: true, help: 'Center point label (e.g. A)' },
+    { name: 'radius', required: false, help: 'Radius value (number) or a point label on the circle' },
+    { name: 'point', required: false, help: 'Alternative: a point label on the circle (use instead of --radius for Circle(center,point))' },
+  ],
+  columns: ['label', 'center', 'radius'],
+  func: async (page, kwargs) => {
+    const center = normalizeLabel(kwargs.center, 'center');
+    if (kwargs.point && kwargs.radius !== undefined) {
+      throw new ArgumentError('Use either --point or --radius, not both');
+    }
+    const pointOnCircle = kwargs.point ? normalizeLabel(kwargs.point, 'point') : '';
+    const radiusValue = kwargs.radius;
+
+    let cmd;
+    if (pointOnCircle) {
+      cmd = `Circle(${center},${pointOnCircle})`;
+    } else if (radiusValue !== undefined) {
+      const raw = String(radiusValue).trim();
+      const num = Number(raw);
+      cmd = Number.isFinite(num)
+        ? `Circle(${center},${normalizeNumber(raw, 'radius', { positive: true })})`
+        : `Circle(${center},${normalizeLabel(raw, 'radius point')})`;
+    } else {
+      throw new ArgumentError('Provide --radius (number or point label) or --point (point on circle)');
+    }
+
+    await ensureApplet(page);
+    const result = requireGgbSuccess(await ggbEval(page, cmd), `Failed to create circle: ${cmd}`);
+    return [{ label: result.label, center, radius: pointOnCircle || radiusValue }];
+  },
+});

package/clis/geogebra/add-line.js

@@ -0,0 +1,35 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbEval, normalizeLabelList, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'add-line',
+  access: 'write',
+  description: 'Create a line through two points or a segment between two points',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra add-line --points A,B --type segment',
+  args: [
+    { name: 'points', required: true, help: 'Two point labels separated by comma (e.g. "A,B")' },
+    { name: 'type', required: false, choices: ['line', 'segment', 'ray'], default: 'line', help: 'Type: line, segment, or ray (default: line)' },
+  ],
+  columns: ['label', 'type', 'points'],
+  func: async (page, kwargs) => {
+    const [a, b] = normalizeLabelList(kwargs.points, 'points', 2, 2);
+    const type = kwargs.type || 'line';
+    const geogebraCmd = {
+      line: `Line(${a},${b})`,
+      segment: `Segment(${a},${b})`,
+      ray: `Ray(${a},${b})`,
+    }[type];
+    if (!geogebraCmd) {
+      throw new ArgumentError('type must be one of: line, segment, ray');
+    }
+    await ensureApplet(page);
+    const result = requireGgbSuccess(await ggbEval(page, geogebraCmd), `Failed to create ${type}: ${geogebraCmd}`);
+    return [{ label: result.label, type, points: `${a},${b}` }];
+  },
+});