@jackwener/opencli 1.7.12 → 1.7.14

package/clis/weixin/search.js

@@ -0,0 +1,157 @@
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+const SOGOU_WEIXIN_DOMAIN = 'weixin.sogou.com';
+const DEFAULT_PAGE = 1;
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 10;
+
+function normalizePositiveInteger(value, name, defaultValue, maxValue) {
+    if (value === undefined || value === null)
+        return defaultValue;
+    const text = String(value).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new ArgumentError(`weixin search --${name} must be a positive integer`, `Pass --${name} as a whole number${maxValue ? ` from 1 to ${maxValue}` : ' greater than 0'}.`);
+    }
+    const parsed = Number(text);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || (maxValue && parsed > maxValue)) {
+        throw new ArgumentError(`weixin search --${name} is out of range`, `Pass --${name} as a whole number${maxValue ? ` from 1 to ${maxValue}` : ' greater than 0'}.`);
+    }
+    return parsed;
+}
+
+function normalizePage(page) {
+    return normalizePositiveInteger(page, 'page', DEFAULT_PAGE);
+}
+
+function normalizeLimit(limit) {
+    return normalizePositiveInteger(limit, 'limit', DEFAULT_LIMIT, MAX_LIMIT);
+}
+
+function buildSearchUrl(query, pageNo) {
+    const searchUrl = new URL('https://weixin.sogou.com/weixin');
+    searchUrl.searchParams.set('query', query);
+    searchUrl.searchParams.set('type', '2');
+    searchUrl.searchParams.set('page', String(pageNo));
+    searchUrl.searchParams.set('ie', 'utf8');
+    return searchUrl.toString();
+}
+
+function buildExtractSearchResultsEvaluate() {
+    return String.raw`(() => {
+        const clean = (value) => {
+            return (value || '')
+                .replace(/\s+/g, ' ')
+                .replace(/<!--red_beg-->|<!--red_end-->/g, '')
+                .replace(/document\.write\(timeConvert\('\d+'\)\)/g, '')
+                .trim();
+        };
+
+        const absolutize = (href) => {
+            if (!href) return '';
+            try {
+                return new URL(href, window.location.origin).toString();
+            } catch {
+                return href;
+            }
+        };
+
+        const bodyText = clean(document.body && document.body.innerText);
+        const blocked = /验证码|安全验证|异常访问|访问过于频繁|请输入验证码/.test(bodyText);
+        const empty = /没有找到相关的微信文章|未找到相关|暂无相关|没有找到/.test(bodyText)
+            || Boolean(document.querySelector('.no-result, .no_result, .s-noresult'));
+        const cards = Array.from(document.querySelectorAll('.news-list li'));
+        const extracted = cards.map((item) => {
+            const linkEl = item.querySelector('h3 a[href]');
+            const summaryEl = item.querySelector('p.txt-info');
+            const timeEl = item.querySelector('.s-p .s2');
+            return {
+                title: clean(linkEl && linkEl.textContent),
+                url: absolutize(linkEl && linkEl.getAttribute('href')),
+                summary: clean(summaryEl && summaryEl.textContent),
+                publish_time: clean(timeEl && timeEl.textContent),
+            };
+        });
+        const rows = extracted.filter((row) => row.title && row.url);
+
+        return {
+            blocked,
+            empty,
+            cardCount: cards.length,
+            invalidCount: extracted.length - rows.length,
+            rows,
+        };
+    })()`;
+}
+
+cli({
+    site: 'weixin',
+    name: 'search',
+    access: 'read',
+    description: '使用搜狗微信搜索公众号文章；如需导出正文 Markdown，请使用 weixin download 处理公众号文章链接',
+    domain: SOGOU_WEIXIN_DOMAIN,
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'query', positional: true, required: true, help: '搜索关键词；如需正文 Markdown，请使用 weixin download 处理公众号文章链接' },
+        { name: 'page', type: 'int', default: 1, help: '结果页码，从 1 开始' },
+        { name: 'limit', type: 'int', default: 10, help: '返回条数，最大 10' },
+    ],
+    columns: ['rank', 'page', 'title', 'url', 'summary', 'publish_time'],
+    func: async (page, kwargs) => {
+        const query = String(kwargs.query ?? '').trim();
+        if (!query) {
+            throw new ArgumentError('A search query is required.', 'Pass a non-empty keyword to search Weixin articles via Sogou.');
+        }
+
+        const pageNo = normalizePage(kwargs.page);
+        const limit = normalizeLimit(kwargs.limit);
+        const searchUrl = buildSearchUrl(query, pageNo);
+
+        let payload;
+        try {
+            await page.goto(searchUrl);
+            await page.wait(2);
+            payload = await page.evaluate(buildExtractSearchResultsEvaluate());
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new CommandExecutionError('weixin search failed while loading Sogou results', detail);
+        }
+
+        if (!payload || typeof payload !== 'object' || !Array.isArray(payload.rows)) {
+            throw new CommandExecutionError('weixin search returned an unreadable browser payload', 'Sogou Weixin may have changed its result page structure.');
+        }
+        if (payload.blocked) {
+            throw new CommandExecutionError('Sogou Weixin blocked this search request', 'Open weixin.sogou.com in Chrome and complete any verification before retrying.');
+        }
+        if (payload.invalidCount > 0) {
+            throw new CommandExecutionError('Sogou Weixin returned article cards without required title or URL', 'The result page structure may have changed; refusing to return a partial result set.');
+        }
+
+        const rows = payload.rows;
+        if (rows.length === 0 && payload.empty) {
+            throw new EmptyResultError('weixin search', 'Try a different keyword or a different page number.');
+        }
+        if (rows.length === 0) {
+            throw new CommandExecutionError('weixin search did not expose article result cards', 'Sogou Weixin may have changed its selectors or returned a transient shell page.');
+        }
+
+        return rows.slice(0, limit).map((row, index) => ({
+            rank: (pageNo - 1) * 10 + index + 1,
+            page: pageNo,
+            title: row.title,
+            url: row.url,
+            summary: row.summary,
+            publish_time: row.publish_time,
+        }));
+    },
+});
+
+export const __test__ = {
+    MAX_LIMIT,
+    normalizePage,
+    normalizeLimit,
+    buildSearchUrl,
+    buildExtractSearchResultsEvaluate,
+};

package/clis/weixin/search.test.js

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { __test__ } from './search.js';
+
+describe('weixin search command', () => {
+    const command = getRegistry().get('weixin/search');
+
+    it('registers as a public browser command', () => {
+        expect(command).toBeDefined();
+        expect(command.site).toBe('weixin');
+        expect(command.strategy).toBe('public');
+        expect(command.browser).toBe(true);
+    });
+
+    it('rejects empty queries before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+
+        await expect(command.func(page, { query: '   ' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('rejects invalid page and limit values before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+
+        await expect(command.func(page, { query: 'AI', page: 0 })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        await expect(command.func(page, { query: 'AI', limit: 11 })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        await expect(command.func(page, { query: 'AI', limit: '2abc' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('uses page and limit while preserving per-page ranking', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                blocked: false,
+                empty: false,
+                cardCount: 2,
+                invalidCount: 0,
+                rows: [
+                    {
+                        title: 'First article',
+                        url: 'https://weixin.sogou.com/link?url=abc',
+                        summary: 'First summary',
+                        publish_time: '2小时前',
+                    },
+                    {
+                        title: 'Second article',
+                        url: 'https://weixin.sogou.com/link?url=def',
+                        summary: 'Second summary',
+                        publish_time: '1小时前',
+                    },
+                ],
+            }),
+        };
+
+        const result = await command.func(page, { query: 'AI', page: 2, limit: 1 });
+
+        expect(page.goto).toHaveBeenCalledWith('https://weixin.sogou.com/weixin?query=AI&type=2&page=2&ie=utf8');
+        expect(result).toEqual([
+            {
+                rank: 11,
+                page: 2,
+                title: 'First article',
+                url: 'https://weixin.sogou.com/link?url=abc',
+                summary: 'First summary',
+                publish_time: '2小时前',
+            },
+        ]);
+    });
+
+    it('preserves browser-side cleanup regex escapes', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                blocked: false,
+                empty: false,
+                cardCount: 1,
+                invalidCount: 0,
+                rows: [
+                    {
+                        title: 'Article',
+                        url: 'https://weixin.sogou.com/link?url=abc',
+                        summary: 'Summary',
+                        publish_time: '2024-4-28',
+                    },
+                ],
+            }),
+        };
+
+        await command.func(page, { query: 'AI' });
+
+        const script = page.evaluate.mock.calls[0][0];
+        expect(script).toContain(".replace(/\\s+/g, ' ')");
+        expect(script).toContain(".replace(/document\\.write\\(timeConvert\\('\\d+'\\)\\)/g, '')");
+    });
+
+    it('maps browser navigation failures to CommandExecutionError', async () => {
+        const page = {
+            goto: vi.fn().mockRejectedValue(new Error('net::ERR_FAILED')),
+        };
+
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('fails fast on unreadable payloads, verification blocks, and partial card extraction', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn(),
+        };
+
+        page.evaluate.mockResolvedValueOnce(null);
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+
+        page.evaluate.mockResolvedValueOnce({ blocked: true, empty: false, cardCount: 0, invalidCount: 0, rows: [] });
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+
+        page.evaluate.mockResolvedValueOnce({ blocked: false, empty: false, cardCount: 2, invalidCount: 1, rows: [{ title: 'Article', url: 'https://example.com' }] });
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('distinguishes explicit empty result pages from selector drift', async () => {
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn()
+                .mockResolvedValueOnce({ blocked: false, empty: true, cardCount: 0, invalidCount: 0, rows: [] })
+                .mockResolvedValueOnce({ blocked: false, empty: false, cardCount: 0, invalidCount: 0, rows: [] }),
+        };
+
+        await expect(command.func(page, { query: 'no-result' })).rejects.toMatchObject({
+            name: 'EmptyResultError',
+            code: 'EMPTY_RESULT',
+        });
+        await expect(command.func(page, { query: 'AI' })).rejects.toMatchObject({
+            name: 'CommandExecutionError',
+            code: 'COMMAND_EXEC',
+        });
+    });
+
+    it('extracts browser DOM payload without silently dropping malformed result cards', async () => {
+        const document = {
+            body: { innerText: 'Article title Summary' },
+            querySelector: vi.fn(() => null),
+            querySelectorAll: vi.fn((selector) => {
+                if (selector !== '.news-list li')
+                    return [];
+                return [
+                    {
+                        querySelector: vi.fn((cardSelector) => {
+                            if (cardSelector === 'h3 a[href]') {
+                                return {
+                                    textContent: 'Article title',
+                                    getAttribute: vi.fn(() => '/link?url=abc'),
+                                };
+                            }
+                            if (cardSelector === 'p.txt-info')
+                                return { textContent: 'Summary' };
+                            if (cardSelector === '.s-p .s2')
+                                return { textContent: '2小时前' };
+                            return null;
+                        }),
+                    },
+                    {
+                        querySelector: vi.fn(() => null),
+                    },
+                ];
+            }),
+        };
+        const window = {
+            location: { origin: 'https://weixin.sogou.com' },
+            URL,
+        };
+        const script = __test__.buildExtractSearchResultsEvaluate();
+        const payload = Function('document', 'window', 'URL', `return ${script};`)(document, window, URL);
+
+        expect(payload).toMatchObject({
+            blocked: false,
+            empty: false,
+            cardCount: 2,
+            invalidCount: 1,
+            rows: [
+                {
+                    title: 'Article title',
+                    url: 'https://weixin.sogou.com/link?url=abc',
+                    summary: 'Summary',
+                    publish_time: '2小时前',
+                },
+            ],
+        });
+    });
+
+    it('exposes pure normalizers for direct regression coverage', () => {
+        expect(__test__.normalizePage(undefined)).toBe(1);
+        expect(__test__.normalizeLimit(undefined)).toBe(10);
+        expect(__test__.normalizeLimit(10)).toBe(10);
+        expect(() => __test__.normalizeLimit(11)).toThrow(/out of range/);
+        expect(__test__.buildSearchUrl('AI tools', 2)).toBe('https://weixin.sogou.com/weixin?query=AI+tools&type=2&page=2&ie=utf8');
+    });
+});

package/clis/wikidata/entity.js

@@ -0,0 +1,60 @@
+// wikidata entity — fetch a single Wikidata entity by Q/P/L identifier.
+//
+// Hits `Special:EntityData/<id>.json`, the canonical public dump. Surfaces the
+// agent-useful projection: localised label/description/aliases plus high-level
+// counts (claim properties, sitelinks). The full claim graph is huge; we keep
+// the projection narrow by design.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { WIKIDATA_BASE, joinAliases, pickLocalised, requireEntityId, requireLanguage, wikidataFetch } from './utils.js';
+
+cli({
+    site: 'wikidata',
+    name: 'entity',
+    access: 'read',
+    description: 'Fetch a Wikidata entity by Q/P/L id (label, description, aliases, claim summary)',
+    domain: 'www.wikidata.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Entity id (e.g. Q937 = Albert Einstein, P31 = instance of)' },
+        { name: 'language', default: 'en', help: 'Display language (ISO 639, falls back to English when missing)' },
+    ],
+    columns: [
+        'qid',
+        'type',
+        'label',
+        'description',
+        'aliases',
+        'claimPropertyCount',
+        'sitelinkCount',
+        'enwikiTitle',
+        'modified',
+        'url',
+    ],
+    func: async (args) => {
+        const qid = requireEntityId(args.id);
+        const language = requireLanguage(args.language);
+        const url = `${WIKIDATA_BASE}/wiki/Special:EntityData/${encodeURIComponent(qid)}.json`;
+        const body = await wikidataFetch(url, 'wikidata entity');
+        const entity = body?.entities?.[qid];
+        if (!entity) {
+            throw new EmptyResultError('wikidata entity', `Wikidata entity ${qid} returned no payload.`);
+        }
+        const claims = entity.claims && typeof entity.claims === 'object' ? entity.claims : {};
+        const sitelinks = entity.sitelinks && typeof entity.sitelinks === 'object' ? entity.sitelinks : {};
+        const enwiki = sitelinks?.enwiki?.title;
+        return [{
+            qid,
+            type: typeof entity.type === 'string' ? entity.type : null,
+            label: pickLocalised(entity.labels, language),
+            description: pickLocalised(entity.descriptions, language),
+            aliases: joinAliases(entity.aliases, language),
+            claimPropertyCount: Object.keys(claims).length,
+            sitelinkCount: Object.keys(sitelinks).length,
+            enwikiTitle: typeof enwiki === 'string' && enwiki.trim() ? enwiki : null,
+            modified: typeof entity.modified === 'string' ? entity.modified : null,
+            url: `${WIKIDATA_BASE}/wiki/${qid}`,
+        }];
+    },
+});

package/clis/wikidata/search.js

@@ -0,0 +1,50 @@
+// wikidata search — find Wikidata entities (items) by keyword.
+//
+// Hits `wbsearchentities` on the public MediaWiki API. Returns Q-IDs that
+// round-trip into `wikidata entity` for full detail.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { WIKIDATA_BASE, requireBoundedInt, requireLanguage, requireString, wikidataFetch } from './utils.js';
+
+cli({
+    site: 'wikidata',
+    name: 'search',
+    access: 'read',
+    description: 'Search Wikidata items by keyword (returns Q-IDs)',
+    domain: 'www.wikidata.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (label / alias)' },
+        { name: 'language', default: 'en', help: 'Search & display language (ISO 639, e.g. en, fr, zh)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max items (1-50)' },
+    ],
+    columns: ['rank', 'qid', 'label', 'description', 'matchType', 'matchText', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const language = requireLanguage(args.language);
+        const limit = requireBoundedInt(args.limit, 20, 50);
+        const url = `${WIKIDATA_BASE}/w/api.php?action=wbsearchentities`
+            + `&search=${encodeURIComponent(query)}`
+            + `&language=${encodeURIComponent(language)}`
+            + `&uselang=${encodeURIComponent(language)}`
+            + `&type=item&format=json&limit=${limit}&origin=*`;
+        const body = await wikidataFetch(url, 'wikidata search');
+        const list = Array.isArray(body?.search) ? body.search : [];
+        if (!list.length) {
+            throw new EmptyResultError('wikidata search', `No Wikidata items matched "${query}" in language "${language}".`);
+        }
+        return list.slice(0, limit).map((item, i) => {
+            const qid = String(item?.id ?? '').trim();
+            return {
+                rank: i + 1,
+                qid,
+                label: typeof item?.label === 'string' ? item.label : null,
+                description: typeof item?.description === 'string' ? item.description : null,
+                matchType: typeof item?.match?.type === 'string' ? item.match.type : null,
+                matchText: typeof item?.match?.text === 'string' ? item.match.text : null,
+                url: qid ? `${WIKIDATA_BASE}/wiki/${qid}` : '',
+            };
+        });
+    },
+});

package/clis/wikidata/utils.js

@@ -0,0 +1,117 @@
+// Shared helpers for the Wikidata adapters.
+//
+// Wikidata exposes two complementary public endpoints:
+//   • `wbsearchentities` on `www.wikidata.org/w/api.php` for keyword → Q-IDs
+//   • `Special:EntityData/<qid>.json` for the canonical entity dump
+// No API key. Anonymous traffic is rate-limited but generous; we set a polite UA.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const WIKIDATA_BASE = 'https://www.wikidata.org';
+const UA = 'opencli-wikidata-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';
+
+// Q-ID = an item; P-ID = a property; L-ID = a lexeme. We accept all three so the
+// adapter can be reused for properties / lexemes without a separate command, but
+// search only returns Q-IDs by default.
+const ENTITY_ID_PATTERN = /^[QPL]\d+$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`wikidata ${label} cannot be empty`);
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`wikidata ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`wikidata ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireEntityId(value) {
+    const raw = String(value ?? '').trim().toUpperCase();
+    if (!raw) throw new ArgumentError('wikidata entity id is required (e.g. "Q937")');
+    // Tolerate URL-paste like `https://www.wikidata.org/wiki/Q937`.
+    const stripped = raw.replace(/^HTTPS?:\/\/[^/]+\/WIKI\//i, '');
+    if (!ENTITY_ID_PATTERN.test(stripped)) {
+        throw new ArgumentError(
+            `wikidata entity id "${value}" is not a valid Q/P/L identifier`,
+            'Expected format: "Q<digits>" (item), "P<digits>" (property), or "L<digits>" (lexeme).',
+        );
+    }
+    return stripped;
+}
+
+export function requireLanguage(value, defaultValue = 'en') {
+    const raw = String(value ?? defaultValue).trim().toLowerCase();
+    // Wikidata language codes are 2-3 letter ISO 639 codes plus optional region (`zh-hans`).
+    if (!/^[a-z]{2,3}(-[a-z]{2,8})?$/.test(raw)) {
+        throw new ArgumentError(
+            `wikidata language "${value}" is not a valid language code`,
+            'Expected an ISO 639 language code such as "en", "fr", "zh", "zh-hans".',
+        );
+    }
+    return raw;
+}
+
+export async function wikidataFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that www.wikidata.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Wikidata returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Wikidata throttles anonymous traffic; back off and retry.',
+        );
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+/**
+ * Pick a localised label / description from a `{<lang>: {value}}` map.
+ * Falls back to English if the requested language is missing.
+ */
+export function pickLocalised(map, language) {
+    if (!map || typeof map !== 'object') return null;
+    const direct = map[language];
+    if (direct && typeof direct.value === 'string' && direct.value.trim()) return direct.value;
+    if (language !== 'en' && map.en && typeof map.en.value === 'string' && map.en.value.trim()) {
+        return map.en.value;
+    }
+    return null;
+}
+
+export function joinAliases(aliases, language, max = 5) {
+    if (!aliases || typeof aliases !== 'object') return '';
+    // Mirror the label/description fallback: prefer requested language, then English.
+    let list = Array.isArray(aliases[language]) ? aliases[language] : [];
+    if (list.length === 0 && language !== 'en' && Array.isArray(aliases.en)) list = aliases.en;
+    const names = list.map((a) => (a && typeof a.value === 'string' ? a.value : '')).filter(Boolean);
+    if (names.length === 0) return '';
+    if (names.length > max) return [...names.slice(0, max), `(+${names.length - max})`].join(', ');
+    return names.join(', ');
+}