@yangfei_93sky/biocli 0.2.0

package/dist/clis/_shared/xml-helpers.js

@@ -0,0 +1,266 @@
+/**
+ * PubMed & Gene XML parsing helpers.
+ *
+ * After fast-xml-parser processes NCBI XML (see xml-parser.ts), the
+ * result is a deeply nested JS object.  These helpers navigate that
+ * structure and return flat, typed records suitable for CLI table output.
+ *
+ * NOTE: The xml-parser config uses:
+ *   - '@_' prefix for attributes  (e.g. @_EIdType)
+ *   - '#text' for text nodes
+ *   - Tags listed in ARRAY_TAGS are always arrays (Author, PubmedArticle, etc.)
+ */
+import { isRecord } from '../../utils.js';
+import { truncate } from './common.js';
+/**
+ * Safely drill into a nested object by a dot-separated path.
+ * Returns `undefined` if any intermediate key is missing.
+ */
+function dig(obj, ...keys) {
+    let cur = obj;
+    for (const k of keys) {
+        if (!isRecord(cur))
+            return undefined;
+        cur = cur[k];
+    }
+    return cur;
+}
+/** Coerce a value to a string, returning '' for nullish values. */
+function str(v) {
+    if (v === undefined || v === null)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return String(v);
+    // fast-xml-parser may produce { '#text': 'value' } for text-only nodes
+    if (isRecord(v) && '#text' in v)
+        return String(v['#text']);
+    return String(v);
+}
+/**
+ * Format author list from parsed Author array.
+ *
+ * Each Author element is typically:
+ *   { LastName: 'Smith', ForeName: 'John', Initials: 'J' }
+ * or sometimes:
+ *   { CollectiveName: 'COVID-19 Genomics UK Consortium' }
+ *
+ * Returns first 3 authors as "LastName FN, ..." plus "et al." if more.
+ */
+function formatAuthors(authorList) {
+    if (!Array.isArray(authorList))
+        return '';
+    const names = [];
+    for (const author of authorList) {
+        if (!isRecord(author))
+            continue;
+        if (author.CollectiveName) {
+            names.push(str(author.CollectiveName));
+        }
+        else {
+            const last = str(author.LastName);
+            const fore = str(author.ForeName);
+            if (last) {
+                names.push(fore ? `${last} ${fore.charAt(0)}` : last);
+            }
+        }
+    }
+    if (names.length === 0)
+        return '';
+    if (names.length <= 3)
+        return names.join(', ');
+    return names.slice(0, 3).join(', ') + ' et al.';
+}
+/**
+ * Extract DOI from Article's ELocationID list.
+ *
+ * ELocationID can be a single object or array (though xml-parser doesn't
+ * force it into an array since it's not in ARRAY_TAGS).  We check for
+ * @_EIdType === 'doi'.
+ */
+function extractDoi(article) {
+    const eloc = article.ELocationID;
+    if (!eloc)
+        return '';
+    const candidates = Array.isArray(eloc) ? eloc : [eloc];
+    for (const entry of candidates) {
+        if (isRecord(entry) && entry['@_EIdType'] === 'doi') {
+            return str(entry['#text'] ?? entry);
+        }
+    }
+    return '';
+}
+/**
+ * Extract publication year from a Journal > JournalIssue > PubDate node.
+ */
+function extractYear(article) {
+    // Try Journal > JournalIssue > PubDate > Year
+    const journalYear = str(dig(article, 'Journal', 'JournalIssue', 'PubDate', 'Year'));
+    if (journalYear)
+        return journalYear;
+    // Fallback: Journal > JournalIssue > PubDate > MedlineDate (e.g. "2024 Jan-Feb")
+    const medlineDate = str(dig(article, 'Journal', 'JournalIssue', 'PubDate', 'MedlineDate'));
+    if (medlineDate) {
+        const yearMatch = medlineDate.match(/\d{4}/);
+        if (yearMatch)
+            return yearMatch[0];
+    }
+    return '';
+}
+/**
+ * Extract abstract text.
+ *
+ * AbstractText is always an array (from ARRAY_TAGS).  Each element may be
+ * a plain string or an object with @_Label and #text (structured abstracts).
+ */
+function extractAbstract(article) {
+    const abstractNode = article.Abstract;
+    if (!isRecord(abstractNode))
+        return '';
+    const textList = abstractNode.AbstractText;
+    if (!Array.isArray(textList))
+        return str(textList);
+    // Structured abstract: multiple labeled sections
+    const parts = [];
+    for (const part of textList) {
+        if (isRecord(part)) {
+            const label = str(part['@_Label']);
+            const text = str(part['#text'] ?? part);
+            parts.push(label ? `${label}: ${text}` : text);
+        }
+        else {
+            parts.push(str(part));
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * Parse a PubMed efetch XML response (after fast-xml-parser processing)
+ * into an array of PubmedArticle records.
+ */
+export function parsePubmedArticles(parsed) {
+    if (!isRecord(parsed))
+        return [];
+    // Top-level key is PubmedArticleSet
+    const articleSet = parsed.PubmedArticleSet;
+    if (!isRecord(articleSet))
+        return [];
+    // PubmedArticle is always an array (from ARRAY_TAGS)
+    const articles = articleSet.PubmedArticle;
+    if (!Array.isArray(articles))
+        return [];
+    const results = [];
+    for (const pa of articles) {
+        if (!isRecord(pa))
+            continue;
+        const citation = pa.MedlineCitation;
+        if (!isRecord(citation))
+            continue;
+        const pmid = str(isRecord(citation.PMID)
+            ? citation.PMID['#text']
+            : citation.PMID);
+        const article = citation.Article;
+        if (!isRecord(article))
+            continue;
+        const articleRec = article;
+        // Title may be a string or { '#text': '...' } with inline markup
+        const title = str(articleRec.ArticleTitle).replace(/<[^>]+>/g, '');
+        // Authors
+        const authorListNode = articleRec.AuthorList;
+        const authorArray = isRecord(authorListNode)
+            ? authorListNode.Author
+            : undefined;
+        const authors = formatAuthors(authorArray);
+        // Journal title
+        const journal = str(dig(articleRec, 'Journal', 'Title'));
+        // Year
+        const year = extractYear(articleRec);
+        // DOI
+        const doi = extractDoi(articleRec);
+        // Abstract
+        const abstract = extractAbstract(articleRec);
+        results.push({ pmid, title, authors, journal, year, doi, abstract });
+    }
+    return results;
+}
+/**
+ * Parse Gene esummary JSON response into GeneInfo records.
+ *
+ * The esummary JSON for the gene database has the structure:
+ * {
+ *   result: {
+ *     uids: ["7157", ...],
+ *     "7157": { uid: "7157", name: "TP53", description: "...", ... }
+ *   }
+ * }
+ */
+export function parseGeneSummaries(parsed) {
+    if (!isRecord(parsed))
+        return [];
+    const resultObj = parsed.result;
+    if (!isRecord(resultObj))
+        return [];
+    const uids = resultObj.uids;
+    if (!Array.isArray(uids))
+        return [];
+    const results = [];
+    for (const uid of uids) {
+        const entry = resultObj[String(uid)];
+        if (!isRecord(entry))
+            continue;
+        const rec = entry;
+        results.push({
+            geneId: str(rec.uid),
+            symbol: str(rec.name),
+            name: str(rec.description),
+            organism: str(dig(rec, 'organism', 'scientificname') ?? rec.orgname),
+            summary: truncate(str(rec.summary), 300),
+            chromosome: str(rec.chromosome),
+            location: str(rec.maplocation),
+        });
+    }
+    return results;
+}
+/**
+ * Parse Gene efetch XML response (Entrezgene-Set) into GeneInfo records.
+ *
+ * Gene efetch XML has the structure:
+ *   Entrezgene-Set > Entrezgene[] > Entrezgene_track-info > Gene-track > Gene-track_geneid
+ *   etc.
+ *
+ * This is considerably more complex than esummary, so we prefer esummary
+ * for most gene commands.  This parser is provided for completeness.
+ */
+export function parseGeneEntries(parsed) {
+    if (!isRecord(parsed))
+        return [];
+    const entrezSet = parsed['Entrezgene-Set'];
+    if (!isRecord(entrezSet))
+        return [];
+    const genes = entrezSet.Entrezgene;
+    if (!Array.isArray(genes))
+        return [];
+    const results = [];
+    for (const gene of genes) {
+        if (!isRecord(gene))
+            continue;
+        const g = gene;
+        // Gene ID
+        const geneId = str(dig(g, 'Entrezgene_track-info', 'Gene-track', 'Gene-track_geneid'));
+        // Symbol and name from Entrezgene_gene > Gene-ref
+        const geneRef = dig(g, 'Entrezgene_gene', 'Gene-ref');
+        const symbol = isRecord(geneRef) ? str(geneRef['Gene-ref_locus']) : '';
+        const name = isRecord(geneRef) ? str(geneRef['Gene-ref_desc']) : '';
+        // Organism from Entrezgene_source > BioSource > BioSource_org > Org-ref > Org-ref_taxname
+        const organism = str(dig(g, 'Entrezgene_source', 'BioSource', 'BioSource_org', 'Org-ref', 'Org-ref_taxname'));
+        // Summary
+        const summary = truncate(str(g['Entrezgene_summary']), 300);
+        // Chromosome & location from Entrezgene_gene > Gene-ref
+        const chromosome = isRecord(geneRef) ? str(geneRef['Gene-ref_maploc']) : '';
+        // Map location (more specific)
+        const location = str(dig(g, 'Entrezgene_location'));
+        results.push({ geneId, symbol, name, organism, summary, chromosome, location });
+    }
+    return results;
+}

package/dist/clis/aggregate/enrichment.d.ts

@@ -0,0 +1,7 @@
+/**
+ * aggregate/enrichment — Combined enrichment analysis from Enrichr + STRING.
+ *
+ * Queries both Enrichr and STRING functional enrichment in parallel,
+ * merges and deduplicates results into a unified enrichment report.
+ */
+export {};

package/dist/clis/aggregate/enrichment.js

@@ -0,0 +1,105 @@
+/**
+ * aggregate/enrichment — Combined enrichment analysis from Enrichr + STRING.
+ *
+ * Queries both Enrichr and STRING functional enrichment in parallel,
+ * merges and deduplicates results into a unified enrichment report.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { submitGeneList, getEnrichment } from '../../databases/enrichr.js';
+import { buildStringUrl, encodeStringIds } from '../../databases/string-db.js';
+import { createHttpContextForDatabase } from '../../databases/index.js';
+import { wrapResult } from '../../types.js';
+cli({
+    site: 'aggregate',
+    name: 'enrichment',
+    description: 'Combined pathway enrichment from Enrichr + STRING',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 60,
+    args: [
+        { name: 'genes', positional: true, required: true, help: 'Comma-separated gene symbols (e.g. TP53,BRCA1,EGFR,MYC,CDK2)' },
+        { name: 'library', default: 'KEGG_2021_Human', help: 'Enrichr library (e.g. GO_Biological_Process_2023, Reactome_2022)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max results per source (1-50)' },
+        { name: 'species', type: 'int', default: 9606, help: 'NCBI taxonomy ID for STRING (default: 9606)' },
+    ],
+    columns: ['term', 'category', 'source', 'pValue', 'genes'],
+    func: async (_ctx, args) => {
+        const geneList = String(args.genes).split(',').map(s => s.trim()).filter(Boolean);
+        if (geneList.length < 2) {
+            throw new CliError('ARGUMENT', 'At least 2 genes required', 'Example: biocli aggregate enrichment TP53,BRCA1,EGFR,MYC,CDK2');
+        }
+        const library = String(args.library);
+        const limit = Math.max(1, Math.min(Number(args.limit), 50));
+        const species = String(args.species);
+        const errors = [];
+        // Run both in parallel
+        const [enrichrResult, stringResult] = await Promise.allSettled([
+            // Enrichr: 2-step workflow
+            (async () => {
+                const userListId = await submitGeneList(geneList);
+                const results = await getEnrichment(userListId, library);
+                return results.slice(0, limit).map(r => ({
+                    term: String(r.term),
+                    category: library,
+                    source: 'Enrichr',
+                    pValue: Number(r.adjustedPValue).toExponential(2),
+                    genes: String(r.genes),
+                }));
+            })(),
+            // STRING functional enrichment
+            (async () => {
+                const stringCtx = createHttpContextForDatabase('string');
+                const data = await stringCtx.fetchJson(buildStringUrl('enrichment', {
+                    identifiers: encodeStringIds(geneList),
+                    species,
+                }));
+                if (!Array.isArray(data))
+                    return [];
+                return data
+                    .filter(item => {
+                    // Only keep KEGG/GO/Reactome categories
+                    const cat = String(item.category ?? '');
+                    return ['Process', 'Function', 'Component', 'KEGG', 'Reactome'].some(c => cat.includes(c));
+                })
+                    .slice(0, limit)
+                    .map(item => {
+                    const inputGenes = item.inputGenes;
+                    const geneStr = Array.isArray(inputGenes) ? inputGenes.join(',') : String(inputGenes ?? '');
+                    return {
+                        term: String(item.description ?? item.term ?? ''),
+                        category: String(item.category ?? ''),
+                        source: 'STRING',
+                        pValue: Number(item.fdr ?? 1).toExponential(2),
+                        genes: geneStr,
+                    };
+                });
+            })(),
+        ]);
+        const rows = [];
+        if (enrichrResult.status === 'fulfilled') {
+            rows.push(...enrichrResult.value);
+        }
+        else {
+            errors.push(`Enrichr: ${enrichrResult.reason}`);
+        }
+        if (stringResult.status === 'fulfilled') {
+            rows.push(...stringResult.value);
+        }
+        else {
+            errors.push(`STRING: ${stringResult.reason}`);
+        }
+        if (!rows.length) {
+            throw new CliError('NOT_FOUND', 'No enrichment results from any source', errors.length ? `Errors: ${errors.join('; ')}` : 'Try adding more genes');
+        }
+        // Sort by p-value
+        rows.sort((a, b) => parseFloat(a.pValue) - parseFloat(b.pValue));
+        const activeSources = [...new Set(rows.map(r => r.source))];
+        return wrapResult(rows, {
+            sources: activeSources,
+            warnings: errors,
+            query: geneList.join(','),
+        });
+    },
+});

package/dist/clis/aggregate/gene-dossier.d.ts

@@ -0,0 +1,13 @@
+/**
+ * aggregate/gene-dossier — Comprehensive gene intelligence report.
+ *
+ * Builds on gene-profile and adds:
+ *   - Recent PubMed literature (top papers)
+ *   - ClinVar clinical significance
+ *   - Summary assessment for agent consumption
+ *
+ * This is the highest-level gene command — a complete "dossier" that
+ * an AI agent can use to understand a gene's biological role, clinical
+ * relevance, and research landscape in one call.
+ */
+export {};

package/dist/clis/aggregate/gene-dossier.js

@@ -0,0 +1,248 @@
+/**
+ * aggregate/gene-dossier — Comprehensive gene intelligence report.
+ *
+ * Builds on gene-profile and adds:
+ *   - Recent PubMed literature (top papers)
+ *   - ClinVar clinical significance
+ *   - Summary assessment for agent consumption
+ *
+ * This is the highest-level gene command — a complete "dossier" that
+ * an AI agent can use to understand a gene's biological role, clinical
+ * relevance, and research landscape in one call.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { wrapResult } from '../../types.js';
+import { createHttpContextForDatabase } from '../../databases/index.js';
+import { buildEutilsUrl } from '../../databases/ncbi.js';
+import { parsePubmedArticles } from '../_shared/xml-helpers.js';
+import { buildUniprotUrl } from '../../databases/uniprot.js';
+import { buildKeggUrl, parseKeggTsv } from '../../databases/kegg.js';
+import { buildStringUrl } from '../../databases/string-db.js';
+import { parseGeneSummaries } from '../_shared/xml-helpers.js';
+import { resolveOrganism } from '../_shared/organism-db.js';
+// Reuse the gene-profile building blocks but add literature + clinical layers
+async function fetchRecentLiterature(ctx, symbol, limit) {
+    // Search PubMed for recent papers about this gene
+    const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+        db: 'pubmed',
+        term: `${symbol} AND "last 5 years"[PDat]`,
+        retmax: String(limit),
+        sort: 'relevance',
+        retmode: 'json',
+    }));
+    const esearch = searchResult?.esearchresult;
+    const pmids = esearch?.idlist ?? [];
+    if (!pmids.length)
+        return [];
+    const xmlData = await ctx.fetchXml(buildEutilsUrl('efetch.fcgi', {
+        db: 'pubmed',
+        id: pmids.join(','),
+        rettype: 'xml',
+    }));
+    const articles = parsePubmedArticles(xmlData);
+    return articles.map(a => ({
+        pmid: a.pmid,
+        title: a.title,
+        authors: a.authors,
+        journal: a.journal,
+        year: a.year,
+        doi: a.doi,
+    }));
+}
+async function fetchClinvarSignificance(ctx, symbol) {
+    const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+        db: 'clinvar',
+        term: `${symbol}[Gene Name]`,
+        retmax: '10',
+        retmode: 'json',
+    }));
+    const ids = searchResult?.esearchresult?.idlist ?? [];
+    if (!ids.length)
+        return [];
+    const summary = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+        db: 'clinvar',
+        id: ids.join(','),
+        retmode: 'json',
+    }));
+    const resultObj = summary?.result;
+    const uids = resultObj?.uids ?? [];
+    return uids.map(uid => {
+        const item = (resultObj?.[uid] ?? {});
+        const sig = typeof item.clinical_significance === 'object'
+            ? item.clinical_significance?.description ?? ''
+            : String(item.clinical_significance ?? '');
+        const traits = Array.isArray(item.trait_set)
+            ? item.trait_set.map(t => String(t.trait_name ?? '')).join('; ')
+            : '';
+        return {
+            title: String(item.title ?? ''),
+            significance: String(sig),
+            condition: traits,
+            accession: String(item.accession ?? ''),
+        };
+    });
+}
+cli({
+    site: 'aggregate',
+    name: 'gene-dossier',
+    description: 'Complete gene intelligence report (profile + literature + clinical)',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 90,
+    args: [
+        { name: 'gene', positional: true, required: true, help: 'Gene symbol (e.g. TP53)' },
+        { name: 'organism', default: 'human', help: 'Organism (e.g. human, mouse)' },
+        { name: 'papers', type: 'int', default: 5, help: 'Number of recent papers to include' },
+    ],
+    columns: ['symbol', 'name', 'pathways', 'interactions', 'literature', 'clinvar'],
+    func: async (_ctx, args) => {
+        const symbol = String(args.gene).trim();
+        if (!symbol)
+            throw new CliError('ARGUMENT', 'Gene symbol is required');
+        const org = resolveOrganism(String(args.organism));
+        const paperCount = Math.max(1, Math.min(Number(args.papers), 20));
+        const sources = [];
+        const warnings = [];
+        const ids = {};
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        const uniprotCtx = createHttpContextForDatabase('uniprot');
+        const keggCtx = createHttpContextForDatabase('kegg');
+        const stringCtx = createHttpContextForDatabase('string');
+        // Phase 1: Core profile (parallel)
+        const [ncbiResult, uniprotResult, stringResult, litResult, clinvarResult] = await Promise.allSettled([
+            // NCBI Gene
+            (async () => {
+                const sr = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                    db: 'gene', term: `${symbol}[Gene Name] AND ${org.name}[Organism]`,
+                    retmax: '5', retmode: 'json',
+                }));
+                const gids = sr?.esearchresult?.idlist ?? [];
+                if (!gids.length)
+                    return null;
+                const summ = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                    db: 'gene', id: gids.join(','), retmode: 'json',
+                }));
+                const genes = parseGeneSummaries(summ);
+                const best = genes.find(g => g.symbol.toUpperCase() === symbol.toUpperCase()) ?? genes[0];
+                return best ?? null;
+            })(),
+            // UniProt
+            (async () => {
+                const data = await uniprotCtx.fetchJson(buildUniprotUrl('/uniprotkb/search', {
+                    query: `gene:${symbol} AND organism_id:${org.taxId} AND reviewed:true`,
+                    format: 'json', size: '1',
+                }));
+                const results = (data?.results ?? []);
+                return results[0] ?? null;
+            })(),
+            // STRING partners
+            (async () => {
+                const data = await stringCtx.fetchJson(buildStringUrl('interaction_partners', {
+                    identifiers: symbol, species: String(org.taxId), limit: '10', required_score: '400',
+                }));
+                return Array.isArray(data) ? data.map(i => ({
+                    partner: String(i.preferredName_B ?? ''),
+                    score: Number(i.score ?? 0),
+                })) : [];
+            })(),
+            // Literature
+            fetchRecentLiterature(ncbiCtx, symbol, paperCount),
+            // ClinVar
+            fetchClinvarSignificance(ncbiCtx, symbol),
+        ]);
+        // Extract NCBI
+        let ncbiGene = null;
+        if (ncbiResult.status === 'fulfilled' && ncbiResult.value) {
+            ncbiGene = ncbiResult.value;
+            sources.push('NCBI Gene');
+            ids.ncbiGeneId = String(ncbiGene.geneId);
+        }
+        else {
+            warnings.push(`NCBI Gene: ${ncbiResult.status === 'rejected' ? ncbiResult.reason : 'not found'}`);
+        }
+        // Extract UniProt (function + GO terms)
+        let uniprotFunc = '';
+        let goTerms = [];
+        if (uniprotResult.status === 'fulfilled' && uniprotResult.value) {
+            const entry = uniprotResult.value;
+            ids.uniprotAccession = String(entry.primaryAccession ?? '');
+            const comments = (entry.comments ?? []);
+            const fc = comments.find(c => c.commentType === 'FUNCTION');
+            const texts = (fc?.texts ?? []);
+            uniprotFunc = texts.map(t => String(t.value ?? '')).join(' ');
+            // Extract GO terms from cross-references
+            const xrefs = (entry.uniProtKBCrossReferences ?? []);
+            goTerms = xrefs
+                .filter(x => x.database === 'GO')
+                .map(x => {
+                const id = String(x.id ?? '');
+                const props = (x.properties ?? []);
+                const termProp = props.find(p => p.key === 'GoTerm');
+                const term = String(termProp?.value ?? '');
+                const aspectMap = { C: 'CC', F: 'MF', P: 'BP' };
+                const [aspect, ...nameParts] = term.split(':');
+                return { id, name: nameParts.join(':'), aspect: aspectMap[aspect] ?? aspect };
+            });
+            sources.push('UniProt');
+        }
+        else {
+            warnings.push(`UniProt: ${uniprotResult.status === 'rejected' ? uniprotResult.reason : 'not found'}`);
+        }
+        // Extract STRING
+        const interactions = stringResult.status === 'fulfilled' ? stringResult.value : [];
+        if (interactions.length)
+            sources.push('STRING');
+        // Extract literature
+        const literature = litResult.status === 'fulfilled' ? litResult.value : [];
+        if (literature.length)
+            sources.push('PubMed');
+        else
+            warnings.push(`PubMed: ${litResult.status === 'rejected' ? litResult.reason : 'no recent papers'}`);
+        // Extract ClinVar
+        const clinvar = clinvarResult.status === 'fulfilled' ? clinvarResult.value : [];
+        if (clinvar.length)
+            sources.push('ClinVar');
+        // KEGG pathways (sequential, needs gene ID)
+        let pathways = [];
+        if (ncbiGene?.geneId) {
+            try {
+                const keggId = `${org.keggOrg}:${ncbiGene.geneId}`;
+                const pathText = await keggCtx.fetchText(buildKeggUrl(`/link/pathway/${keggId}`));
+                if (pathText.trim()) {
+                    const links = parseKeggTsv(pathText);
+                    const pathIds = links.map(l => l.value.replace(/^path:/, '')).filter(Boolean);
+                    const listText = await keggCtx.fetchText(buildKeggUrl(`/list/pathway/${org.keggOrg}`));
+                    const pathMap = new Map(parseKeggTsv(listText).map(p => [p.key, p.value.replace(/ - .*$/, '')]));
+                    pathways = pathIds.map(id => ({ id, name: pathMap.get(id) ?? id }));
+                    ids.keggId = keggId;
+                    sources.push('KEGG');
+                }
+            }
+            catch (err) {
+                warnings.push(`KEGG: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const dossier = {
+            symbol,
+            name: String(ncbiGene?.name ?? ''),
+            summary: String(ncbiGene?.summary ?? ''),
+            function: uniprotFunc,
+            chromosome: String(ncbiGene?.chromosome ?? ''),
+            location: String(ncbiGene?.location ?? ''),
+            pathways,
+            goTerms,
+            interactions,
+            recentLiterature: literature,
+            clinicalVariants: clinvar,
+        };
+        return wrapResult(dossier, {
+            ids,
+            sources,
+            warnings,
+            organism: org.name,
+            query: symbol,
+        });
+    },
+});

package/dist/clis/aggregate/gene-profile.d.ts

@@ -0,0 +1,16 @@
+/**
+ * aggregate/gene-profile — Complete gene profile from multiple databases.
+ *
+ * THE KILLER FEATURE: one command queries NCBI Gene, UniProt, KEGG, and
+ * STRING in parallel and returns a unified, agent-friendly JSON object.
+ *
+ * Supports:
+ *   - Single gene:  biocli aggregate gene-profile TP53
+ *   - Batch:        biocli aggregate gene-profile TP53,BRCA1,EGFR
+ *
+ * Design:
+ *   - Promise.allSettled for partial failure tolerance
+ *   - _meta.sources tracks which databases contributed
+ *   - _meta.errors reports partial failures without crashing
+ */
+export {};