@jackwener/opencli 1.7.11 → 1.7.13

package/clis/openalex/utils.js

@@ -0,0 +1,160 @@
+// Shared helpers for the OpenAlex (`api.openalex.org`) adapter.
+//
+// OpenAlex is a free, open scholarly works database. The REST API is
+// unauthenticated; passing an email via `mailto=` opts into the polite pool
+// (faster). Work IDs are `W` followed by digits (`W2741809807`) and
+// round-trip via `https://api.openalex.org/works/<id>` or
+// `https://openalex.org/W…`.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const OPENALEX_BASE = 'https://api.openalex.org';
+const UA = 'opencli-openalex-adapter (+https://github.com/jackwener/opencli)';
+
+// OpenAlex stable IDs: a single-letter prefix (`W` works, `A` authors, `S`
+// sources, `I` institutions…) + at least 4 digits. We accept just `W` here.
+const WORK_ID = /^W\d{4,}$/;
+// DOIs are loose — accept anything starting with "10." after the optional
+// `doi.org/` prefix; OpenAlex itself does the normalization.
+const DOI_BARE = /^10\.\S+$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`openalex ${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(`openalex ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`openalex ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+/**
+ * Resolve a user-supplied work identifier to OpenAlex's canonical path
+ * segment. Accepts `W…` IDs, `doi:10.…`, raw DOIs, or full
+ * `https://doi.org/…` / `https://openalex.org/W…` URLs.
+ */
+export function requireWorkRef(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) {
+        throw new ArgumentError('openalex work id is required (e.g. "W2741809807", "10.7717/peerj.4375")');
+    }
+    // 1) full openalex URL
+    const oaUrl = raw.match(/^https?:\/\/(?:api\.)?openalex\.org\/(?:works\/)?([WAaSCFwIPwT]\d+)/i);
+    if (oaUrl) {
+        const id = oaUrl[1].toUpperCase();
+        if (id[0] !== 'W') {
+            throw new ArgumentError(`openalex work id "${value}" must be a Work (W…) ID, got "${id[0]}…"`);
+        }
+        return id;
+    }
+    // 2) bare W… id
+    if (WORK_ID.test(raw.toUpperCase())) {
+        return raw.toUpperCase();
+    }
+    // 3) doi:… prefix
+    if (/^doi:/i.test(raw)) {
+        const doi = raw.replace(/^doi:/i, '').trim();
+        if (DOI_BARE.test(doi)) return `doi:${doi}`;
+    }
+    // 4) full doi URL
+    const doiUrl = raw.match(/^https?:\/\/(?:dx\.)?doi\.org\/(.+)$/i);
+    if (doiUrl && DOI_BARE.test(doiUrl[1])) {
+        return `doi:${doiUrl[1]}`;
+    }
+    // 5) bare 10.xxxx/yyy DOI
+    if (DOI_BARE.test(raw)) {
+        return `doi:${raw}`;
+    }
+    throw new ArgumentError(
+        `openalex work id "${value}" is not recognised`,
+        'Use a Work id ("W2741809807"), a DOI ("10.7717/peerj.4375"), or a full openalex.org / doi.org URL.',
+    );
+}
+
+export async function openalexFetch(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 api.openalex.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `OpenAlex returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'OpenAlex throttles unauthenticated traffic; wait a few seconds and retry, or set OPENALEX_MAILTO.',
+        );
+    }
+    if (!resp.ok) {
+        let detail = '';
+        try {
+            const text = await resp.text();
+            const match = text.match(/"message"\s*:\s*"([^"]+)"/);
+            if (match) detail = ` (${match[1]})`;
+        }
+        catch { /* ignore */ }
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}${detail}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+/** Strip the `https://openalex.org/` prefix if present so columns surface just the bare id. */
+export function bareId(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return '';
+    return s.replace(/^https?:\/\/(?:api\.)?openalex\.org\//i, '').replace(/^works\//i, '');
+}
+
+/** Strip the `https://doi.org/` prefix so DOIs render as plain `10.…/…` strings. */
+export function bareDoi(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return '';
+    return s.replace(/^https?:\/\/(?:dx\.)?doi\.org\//i, '');
+}
+
+/**
+ * Reconstruct a plain-text abstract from OpenAlex's
+ * `abstract_inverted_index` (token → [positions]). OpenAlex returns the
+ * abstract this way for licensing reasons.
+ */
+export function reconstructAbstract(invertedIndex) {
+    if (!invertedIndex || typeof invertedIndex !== 'object') return '';
+    const positions = [];
+    for (const [token, idxs] of Object.entries(invertedIndex)) {
+        if (!Array.isArray(idxs)) continue;
+        for (const i of idxs) {
+            if (Number.isInteger(i) && i >= 0 && i < 100000) {
+                positions[i] = token;
+            }
+        }
+    }
+    return positions.filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/** Append the polite-pool `mailto` query param if the env var is set. */
+export function appendMailto(url) {
+    const mailto = process.env.OPENALEX_MAILTO?.trim();
+    if (!mailto) return url;
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}mailto=${encodeURIComponent(mailto)}`;
+}

package/clis/openalex/work.js

@@ -0,0 +1,65 @@
+// openalex work — fetch a single Work's record from OpenAlex.
+//
+// Hits `https://api.openalex.org/works/<id-or-doi>`. Accepts an OpenAlex
+// Work id (`W2741809807`), a raw DOI (`10.7717/peerj.4375`), or a full
+// `doi.org` / `openalex.org` URL. Returns one row plus the (decoded)
+// abstract — OpenAlex stores abstracts as `abstract_inverted_index` so we
+// reconstruct it for downstream readers.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    OPENALEX_BASE,
+    appendMailto,
+    bareDoi,
+    bareId,
+    openalexFetch,
+    reconstructAbstract,
+    requireWorkRef,
+} from './utils.js';
+
+const SELECT_FIELDS = [
+    'id', 'doi', 'title', 'publication_year', 'publication_date',
+    'cited_by_count', 'authorships', 'primary_location', 'open_access', 'type',
+    'referenced_works', 'related_works', 'language', 'abstract_inverted_index',
+].join(',');
+
+cli({
+    site: 'openalex',
+    name: 'work',
+    access: 'read',
+    description: 'Fetch a single OpenAlex Work (paper / preprint / book) — metadata + abstract',
+    domain: 'api.openalex.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'OpenAlex Work id ("W2741809807"), DOI ("10.7717/peerj.4375"), or full URL' },
+    ],
+    columns: ['id', 'title', 'type', 'year', 'date', 'language', 'authors', 'venue', 'citations', 'openAccess', 'openAccessUrl', 'referencedCount', 'doi', 'abstract', 'url'],
+    func: async (args) => {
+        const ref = requireWorkRef(args.id);
+        const url = appendMailto(`${OPENALEX_BASE}/works/${encodeURIComponent(ref)}?select=${SELECT_FIELDS}`);
+        const w = await openalexFetch(url, 'openalex work');
+        const authors = Array.isArray(w.authorships)
+            ? w.authorships.map((a) => String(a?.author?.display_name ?? '').trim()).filter(Boolean).join(', ')
+            : '';
+        const venue = String(w.primary_location?.source?.display_name ?? '').trim();
+        const id = bareId(w.id);
+        const oaUrl = String(w.open_access?.oa_url ?? '').trim();
+        return [{
+            id,
+            title: String(w.title ?? '').trim(),
+            type: String(w.type ?? '').trim(),
+            year: w.publication_year != null ? Number(w.publication_year) : null,
+            date: String(w.publication_date ?? '').trim(),
+            language: String(w.language ?? '').trim(),
+            authors,
+            venue,
+            citations: w.cited_by_count != null ? Number(w.cited_by_count) : null,
+            openAccess: Boolean(w.open_access?.is_oa),
+            openAccessUrl: oaUrl,
+            referencedCount: Array.isArray(w.referenced_works) ? w.referenced_works.length : null,
+            doi: bareDoi(w.doi),
+            abstract: reconstructAbstract(w.abstract_inverted_index),
+            url: id ? `https://openalex.org/${id}` : '',
+        }];
+    },
+});

package/clis/openfda/drug-label.js

@@ -0,0 +1,74 @@
+// openfda drug-label — FDA-approved drug label search.
+//
+// Endpoint: GET /drug/label.json?search=<lucene>&limit=<n>
+// Default search field is brand_name OR generic_name (Lucene syntax via openfda
+// query DSL). Returns label sections (purpose, warnings, dosage, etc.) and
+// metadata (manufacturer, product_ndc, route, etc.).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    OPENFDA_BASE,
+    firstOrNull,
+    joinOrNull,
+    openfdaFetch,
+    requireBoundedInt,
+    requireString,
+} from './utils.js';
+
+cli({
+    site: 'openfda',
+    name: 'drug-label',
+    access: 'read',
+    description: 'Search FDA-approved drug labels (brand or generic name)',
+    domain: 'fda.gov',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Brand or generic drug name (e.g. "aspirin", "lisinopril")' },
+        { name: 'limit', type: 'int', default: 5, help: 'Max rows (1-25, default 5; openFDA caps anonymous tier at 25/page)' },
+    ],
+    columns: [
+        'rank', 'id', 'brandName', 'genericName', 'manufacturer',
+        'productType', 'route', 'productNdc', 'pharmClass',
+        'purpose', 'indications', 'warnings', 'dosage', 'effectiveTime',
+    ],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 5, 25);
+        const brand = `openfda.brand_name:"${query}"`;
+        const generic = `openfda.generic_name:"${query}"`;
+        // URLSearchParams encodes spaces/operators in ways openFDA's Lucene
+        // parser handles poorly. Keep the OR literal visible and encode only
+        // each clause, matching food-recall's manual +AND+ handling.
+        const search = `${encodeURIComponent(brand)}+OR+${encodeURIComponent(generic)}`;
+        const url = `${OPENFDA_BASE}/drug/label.json?search=${search}&limit=${limit}`;
+        const body = await openfdaFetch(url, 'openfda drug-label');
+        const list = Array.isArray(body?.results) ? body.results : [];
+        if (!list.length) {
+            throw new EmptyResultError('openfda drug-label', `openFDA returned no labels matching "${query}".`);
+        }
+        return list.map((r, i) => {
+            const o = r?.openfda ?? {};
+            // pharm_class fields: epc (established pharmacologic class) is the
+            // most user-meaningful — fall back through moa/cs/pe in that order.
+            const pharmClass = firstOrNull(o.pharm_class_epc) ?? firstOrNull(o.pharm_class_moa)
+                ?? firstOrNull(o.pharm_class_cs) ?? firstOrNull(o.pharm_class_pe);
+            return {
+                rank: i + 1,
+                id: r?.id ?? null,
+                brandName: firstOrNull(o.brand_name),
+                genericName: firstOrNull(o.generic_name),
+                manufacturer: firstOrNull(o.manufacturer_name),
+                productType: firstOrNull(o.product_type),
+                route: joinOrNull(o.route),
+                productNdc: firstOrNull(o.product_ndc),
+                pharmClass,
+                purpose: firstOrNull(r.purpose),
+                indications: firstOrNull(r.indications_and_usage),
+                warnings: firstOrNull(r.warnings),
+                dosage: firstOrNull(r.dosage_and_administration),
+                effectiveTime: r?.effective_time ?? null,
+            };
+        });
+    },
+});

package/clis/openfda/food-recall.js

@@ -0,0 +1,65 @@
+// openfda food-recall — FDA food enforcement (recalls, market withdrawals, alerts).
+//
+// Endpoint: GET /food/enforcement.json?search=<lucene>&limit=<n>
+// Sorted by report_date descending (most recent first).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { OPENFDA_BASE, openfdaFetch, requireBoundedInt } from './utils.js';
+
+cli({
+    site: 'openfda',
+    name: 'food-recall',
+    access: 'read',
+    description: 'FDA food recall and enforcement actions (most recent first)',
+    domain: 'fda.gov',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', help: 'Free-text Lucene query (e.g. "salmonella", "listeria"); default: all recent recalls' },
+        { name: 'status', help: 'Filter by status: "Ongoing", "Completed", "Terminated"' },
+        { name: 'classification', help: 'Filter by class: "Class I" (most serious), "Class II", "Class III"' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max rows (1-100, default 10; openFDA caps anonymous tier at 100/page)' },
+    ],
+    columns: [
+        'rank', 'recallNumber', 'status', 'classification', 'voluntary',
+        'recallingFirm', 'city', 'state', 'country',
+        'productDescription', 'reasonForRecall', 'productQuantity',
+        'distributionPattern', 'reportDate', 'recallInitiationDate', 'terminationDate',
+    ],
+    func: async (args) => {
+        const limit = requireBoundedInt(args.limit, 10, 100);
+        const filters = [];
+        if (args.query) filters.push(String(args.query).trim());
+        if (args.status) filters.push(`status:"${String(args.status).trim()}"`);
+        if (args.classification) filters.push(`classification:"${String(args.classification).trim()}"`);
+        // URLSearchParams percent-encodes the `+AND+` separator that openFDA's
+        // Lucene parser treats specially, so build the query string by hand.
+        const qs = filters.length
+            ? `search=${filters.map(f => encodeURIComponent(f)).join('+AND+')}&limit=${limit}`
+            : `limit=${limit}`;
+        const url = `${OPENFDA_BASE}/food/enforcement.json?${qs}`;
+        const body = await openfdaFetch(url, 'openfda food-recall');
+        const list = Array.isArray(body?.results) ? body.results : [];
+        if (!list.length) {
+            throw new EmptyResultError('openfda food-recall', 'openFDA returned no food recall records matching the filter.');
+        }
+        return list.map((r, i) => ({
+            rank: i + 1,
+            recallNumber: r?.recall_number ?? null,
+            status: r?.status ?? null,
+            classification: r?.classification ?? null,
+            voluntary: r?.voluntary_mandated ?? null,
+            recallingFirm: r?.recalling_firm ?? null,
+            city: r?.city ?? null,
+            state: r?.state ?? null,
+            country: r?.country ?? null,
+            productDescription: r?.product_description ?? null,
+            reasonForRecall: r?.reason_for_recall ?? null,
+            productQuantity: r?.product_quantity ?? null,
+            distributionPattern: r?.distribution_pattern ?? null,
+            reportDate: r?.report_date ?? null,
+            recallInitiationDate: r?.recall_initiation_date ?? null,
+            terminationDate: r?.termination_date ?? null,
+        }));
+    },
+});

package/clis/openfda/openfda.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError, CommandExecutionError } from '@jackwener/opencli/errors';
+import './drug-label.js';
+import './food-recall.js';
+
+const origFetch = global.fetch;
+afterEach(() => { global.fetch = origFetch; });
+
+const sampleLabel = {
+    id: 'abcde-12345',
+    effective_time: '20250101',
+    purpose: ['Pain reliever'],
+    indications_and_usage: ['For temporary relief of minor aches and pains.'],
+    warnings: ['Allergy alert: do not use if you are allergic to NSAIDs.'],
+    dosage_and_administration: ['Take 1-2 tablets every 4-6 hours.'],
+    openfda: {
+        brand_name: ['Aspirin Bayer'],
+        generic_name: ['ASPIRIN'],
+        manufacturer_name: ['Bayer HealthCare LLC'],
+        product_type: ['HUMAN OTC DRUG'],
+        route: ['ORAL'],
+        product_ndc: ['0280-1234'],
+        pharm_class_epc: ['Nonsteroidal Anti-inflammatory Drug [EPC]'],
+    },
+};
+
+const sampleRecall = {
+    recall_number: 'F-1234-2026',
+    status: 'Ongoing',
+    classification: 'Class I',
+    voluntary_mandated: 'Voluntary',
+    recalling_firm: 'Acme Foods Inc',
+    city: 'Atlanta', state: 'GA', country: 'United States',
+    product_description: 'Acme Salad Mix 12oz',
+    reason_for_recall: 'Listeria monocytogenes contamination',
+    product_quantity: '20000 cases',
+    distribution_pattern: 'Nationwide',
+    report_date: '20260415',
+    recall_initiation_date: '20260410',
+    termination_date: null,
+};
+
+describe('openfda drug-label', () => {
+    const cmd = getRegistry().get('openfda/drug-label');
+
+    it('rejects empty query', async () => {
+        await expect(cmd.func({ query: '' })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('rejects --limit out of range', async () => {
+        await expect(cmd.func({ query: 'aspirin', limit: 99 })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('promotes 404 to EmptyResultError', async () => {
+        global.fetch = vi.fn(() => Promise.resolve(new Response('{}', { status: 404 })));
+        await expect(cmd.func({ query: 'unobtainium' })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('shapes drug-label rows + collapses 1-elem arrays', async () => {
+        global.fetch = vi.fn(() => Promise.resolve(new Response(JSON.stringify({ results: [sampleLabel] }), { status: 200 })));
+        const rows = await cmd.func({ query: 'aspirin', limit: 1 });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            rank: 1, brandName: 'Aspirin Bayer', genericName: 'ASPIRIN',
+            manufacturer: 'Bayer HealthCare LLC', purpose: 'Pain reliever',
+            pharmClass: 'Nonsteroidal Anti-inflammatory Drug [EPC]',
+        });
+    });
+
+    it('uses brand OR generic search instead of requiring both fields to match', async () => {
+        const calls = [];
+        global.fetch = vi.fn((url) => {
+            calls.push(url);
+            return Promise.resolve(new Response(JSON.stringify({ results: [sampleLabel] }), { status: 200 }));
+        });
+        await cmd.func({ query: 'tylenol', limit: 1 });
+        expect(calls[0]).toContain('+OR+');
+        expect(calls[0]).toContain('openfda.brand_name');
+        expect(calls[0]).toContain('openfda.generic_name');
+    });
+});
+
+describe('openfda food-recall', () => {
+    const cmd = getRegistry().get('openfda/food-recall');
+
+    it('promotes 429 to CommandExecutionError', async () => {
+        global.fetch = vi.fn(() => Promise.resolve(new Response('rate', { status: 429 })));
+        await expect(cmd.func({})).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('shapes food-recall rows + carries report_date', async () => {
+        global.fetch = vi.fn(() => Promise.resolve(new Response(JSON.stringify({ results: [sampleRecall] }), { status: 200 })));
+        const rows = await cmd.func({ classification: 'Class I' });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            rank: 1, recallNumber: 'F-1234-2026', status: 'Ongoing',
+            classification: 'Class I', recallingFirm: 'Acme Foods Inc',
+            reportDate: '20260415',
+        });
+    });
+
+    it('threads --query AND --status into Lucene query string', async () => {
+        const calls = [];
+        global.fetch = vi.fn((url) => {
+            calls.push(url);
+            return Promise.resolve(new Response(JSON.stringify({ results: [sampleRecall] }), { status: 200 }));
+        });
+        await cmd.func({ query: 'salmonella', status: 'Ongoing' });
+        // Verify both clauses survived URL encoding (the literal `+AND+` should NOT be percent-escaped).
+        expect(calls[0]).toContain('+AND+');
+        expect(calls[0]).toContain('salmonella');
+    });
+});

package/clis/openfda/utils.js

@@ -0,0 +1,67 @@
+// openFDA shared helpers — FDA drug labels + food recall enforcement (no auth, public).
+//
+// Free public tier with anonymous rate limit (~240 req/min, 1000 req/day per IP).
+// API key bumps that to 240 req/min × ~120000 req/day, but is not required for
+// modest read traffic.
+import { ArgumentError, EmptyResultError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+export const OPENFDA_BASE = 'https://api.fda.gov';
+const UA = 'opencli-openfda/1.0';
+
+export function requireString(value, name) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new ArgumentError(`--${name} is required`);
+    }
+    return value.trim();
+}
+
+export function requireBoundedInt(value, def, max, name = 'limit') {
+    const n = value == null || value === '' ? def : Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > max) {
+        throw new ArgumentError(`--${name} must be an integer between 1 and ${max}`);
+    }
+    return n;
+}
+
+export async function openfdaFetch(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}`);
+    }
+    if (resp.status === 404) {
+        // openFDA returns 404 for "no matches" instead of an empty results array.
+        throw new EmptyResultError(label, `${label} returned 404 (no matches).`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(`${label} rate-limited (HTTP 429); 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 non-JSON body: ${err.message}`);
+    }
+    return body;
+}
+
+// openFDA returns most string fields as `[string]` arrays — collapse to first
+// element. Preserves `null` (not coerced to empty string) when the slot is
+// missing entirely.
+export function firstOrNull(arr) {
+    if (!Array.isArray(arr) || !arr.length) return null;
+    const v = arr[0];
+    if (typeof v !== 'string') return v ?? null;
+    const trimmed = v.trim();
+    return trimmed.length ? trimmed : null;
+}
+
+// Comma-join an array of strings, preserving null when empty.
+export function joinOrNull(arr, max = 5) {
+    if (!Array.isArray(arr) || !arr.length) return null;
+    return arr.slice(0, max).map(String).join(', ');
+}