@yangfei_93sky/biocli 0.2.0

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

@@ -0,0 +1,305 @@
+/**
+ * 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
+ */
+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 { buildUniprotUrl } from '../../databases/uniprot.js';
+import { buildKeggUrl, parseKeggTsv, parseKeggEntry } 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';
+// ── NCBI Gene fetch ───────────────────────────────────────────────────────────
+async function fetchNcbiGene(ctx, symbol, organism) {
+    // Fetch top 5 candidates to detect ambiguity
+    const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+        db: 'gene', term: `${symbol}[Gene Name] AND ${organism}[Organism]`,
+        retmax: '5', retmode: 'json',
+    }));
+    const ids = searchResult?.esearchresult?.idlist ?? [];
+    if (!ids.length)
+        return null;
+    const summaryResult = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+        db: 'gene', id: ids.join(','), retmode: 'json',
+    }));
+    const genes = parseGeneSummaries(summaryResult);
+    if (!genes.length)
+        return null;
+    // Prefer exact symbol match to avoid returning a wrong gene
+    const exactMatch = genes.find(g => g.symbol.toUpperCase() === symbol.toUpperCase());
+    const best = exactMatch ?? genes[0];
+    return {
+        geneId: best.geneId,
+        name: best.name,
+        summary: best.summary,
+        chromosome: best.chromosome,
+        location: best.location,
+    };
+}
+// ── UniProt fetch ─────────────────────────────────────────────────────────────
+async function fetchUniprotData(ctx, symbol, taxId) {
+    // Fetch top 5 and pick the exact gene name match
+    const query = `gene:${symbol} AND organism_id:${taxId} AND reviewed:true`;
+    const data = await ctx.fetchJson(buildUniprotUrl('/uniprotkb/search', {
+        query, format: 'json', size: '5',
+    }));
+    const results = (data?.results ?? []);
+    if (!results.length)
+        return null;
+    // Find exact gene name match among candidates
+    const getGeneName = (e) => {
+        const genes = e.genes;
+        const primary = genes?.[0];
+        const gn = primary?.geneName;
+        return String(gn?.value ?? '');
+    };
+    const exactMatch = results.find(e => getGeneName(e).toUpperCase() === symbol.toUpperCase());
+    const entry = exactMatch ?? results[0];
+    const accession = String(entry.primaryAccession ?? '');
+    // Function
+    const comments = (entry.comments ?? []);
+    const funcComment = comments.find(c => c.commentType === 'FUNCTION');
+    const funcTexts = (funcComment?.texts ?? []);
+    const funcText = funcTexts.map(t => String(t.value ?? '')).join(' ');
+    // Subcellular location
+    const locComment = comments.find(c => c.commentType === 'SUBCELLULAR LOCATION');
+    const locEntries = (locComment?.subcellularLocations ?? []);
+    const locations = locEntries.map(l => String(l.location?.value ?? '')).filter(Boolean);
+    // GO terms
+    const xrefs = (entry.uniProtKBCrossReferences ?? []);
+    const 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 };
+    });
+    // Ensembl cross-ref
+    const ensemblXref = xrefs.find(x => x.database === 'Ensembl');
+    const ensemblProps = (ensemblXref?.properties ?? []);
+    const ensemblGeneProp = ensemblProps.find(p => p.key === 'GeneId');
+    const ensemblGeneId = ensemblGeneProp ? String(ensemblGeneProp.value) : undefined;
+    return {
+        accession,
+        function: funcText,
+        subcellularLocation: locations.join(', '),
+        goTerms,
+        ensemblGeneId,
+    };
+}
+// ── KEGG fetch ────────────────────────────────────────────────────────────────
+/**
+ * Normalize KEGG pathway IDs: /link/pathway returns "path:hsa04115"
+ * but /list/pathway returns "hsa04115". Strip the "path:" prefix.
+ */
+function normalizeKeggId(id) {
+    return id.replace(/^path:/, '');
+}
+async function fetchKeggData(ctx, keggOrg, geneId, errors) {
+    const keggId = `${keggOrg}:${geneId}`;
+    // Fetch pathways with name resolution
+    let pathways = [];
+    try {
+        const pathText = await ctx.fetchText(buildKeggUrl(`/link/pathway/${keggId}`));
+        if (pathText.trim()) {
+            const links = parseKeggTsv(pathText);
+            const pathIds = links.map(l => l.value).filter(Boolean);
+            if (pathIds.length) {
+                // /list/pathway/hsa returns "hsa04115\tPathway name - Homo sapiens (human)"
+                const listText = await ctx.fetchText(buildKeggUrl(`/list/pathway/${keggOrg}`));
+                const allPaths = parseKeggTsv(listText);
+                const pathMap = new Map(allPaths.map(p => [p.key, p.value.replace(/ - .*$/, '')]));
+                pathways = pathIds.map(rawId => {
+                    const normalized = normalizeKeggId(rawId);
+                    return { id: normalized, name: pathMap.get(normalized) ?? normalized };
+                });
+            }
+        }
+    }
+    catch (err) {
+        errors.push(`KEGG pathways: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Fetch diseases with name resolution (reuse kegg/disease.ts pattern)
+    let diseases = [];
+    try {
+        const diseaseText = await ctx.fetchText(buildKeggUrl(`/link/disease/${keggId}`));
+        if (diseaseText.trim()) {
+            const links = parseKeggTsv(diseaseText);
+            const diseaseIds = links.map(l => l.value).filter(Boolean);
+            // Batch name resolution: /get accepts up to 10 IDs joined with '+'
+            const names = {};
+            for (let i = 0; i < diseaseIds.length; i += 10) {
+                const batch = diseaseIds.slice(i, i + 10);
+                try {
+                    const text = await ctx.fetchText(buildKeggUrl(`/get/${batch.join('+')}`));
+                    for (const entryText of text.split('///').filter(e => e.trim())) {
+                        const parsed = parseKeggEntry(entryText);
+                        if (parsed.ENTRY && parsed.NAME) {
+                            const id = 'ds:' + parsed.ENTRY.split(/\s+/)[0];
+                            names[id] = parsed.NAME;
+                        }
+                    }
+                }
+                catch (err) {
+                    errors.push(`KEGG disease names (batch ${i / 10 + 1}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            diseases = diseaseIds.map(id => ({ id, name: names[id] ?? '' }));
+        }
+    }
+    catch (err) {
+        errors.push(`KEGG diseases: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { keggId, pathways, diseases };
+}
+// ── STRING fetch ──────────────────────────────────────────────────────────────
+async function fetchStringPartners(ctx, symbol, taxId) {
+    // Let errors propagate — Promise.allSettled in the caller handles them
+    const data = await ctx.fetchJson(buildStringUrl('interaction_partners', {
+        identifiers: symbol,
+        species: String(taxId),
+        limit: '10',
+        required_score: '400',
+    }));
+    if (!Array.isArray(data))
+        return [];
+    return data.map(item => ({
+        partner: String(item.preferredName_B ?? ''),
+        score: Number(item.score ?? 0),
+    }));
+}
+// ── Main command ──────────────────────────────────────────────────────────────
+async function buildGeneProfile(symbol, organismName, taxId, keggOrg) {
+    const meta = { sources: [], queriedAt: new Date().toISOString(), errors: [] };
+    const ncbiCtx = createHttpContextForDatabase('ncbi');
+    const uniprotCtx = createHttpContextForDatabase('uniprot');
+    const keggCtx = createHttpContextForDatabase('kegg');
+    const stringCtx = createHttpContextForDatabase('string');
+    // Parallel queries with partial failure tolerance
+    const [ncbiResult, uniprotResult, stringResult] = await Promise.allSettled([
+        fetchNcbiGene(ncbiCtx, symbol, organismName),
+        fetchUniprotData(uniprotCtx, symbol, taxId),
+        fetchStringPartners(stringCtx, symbol, taxId),
+    ]);
+    // Extract NCBI data
+    let ncbiData = null;
+    if (ncbiResult.status === 'fulfilled' && ncbiResult.value) {
+        ncbiData = ncbiResult.value;
+        meta.sources.push('NCBI Gene');
+    }
+    else {
+        meta.errors.push(`NCBI: ${ncbiResult.status === 'rejected' ? ncbiResult.reason : 'no data'}`);
+    }
+    // Extract UniProt data
+    let uniprotData = null;
+    if (uniprotResult.status === 'fulfilled' && uniprotResult.value) {
+        uniprotData = uniprotResult.value;
+        meta.sources.push('UniProt');
+    }
+    else {
+        meta.errors.push(`UniProt: ${uniprotResult.status === 'rejected' ? uniprotResult.reason : 'no data'}`);
+    }
+    // Extract STRING data
+    let interactions = [];
+    if (stringResult.status === 'fulfilled' && stringResult.value.length) {
+        interactions = stringResult.value;
+        meta.sources.push('STRING');
+    }
+    else {
+        meta.errors.push(`STRING: ${stringResult.status === 'rejected' ? stringResult.reason : 'no data'}`);
+    }
+    // KEGG (needs NCBI Gene ID first, so sequential)
+    // Errors are pushed to meta.errors inside fetchKeggData, not silently swallowed
+    let keggData = null;
+    if (ncbiData?.geneId) {
+        try {
+            keggData = await fetchKeggData(keggCtx, keggOrg, ncbiData.geneId, meta.errors);
+            if (keggData.pathways.length || keggData.diseases.length) {
+                meta.sources.push('KEGG');
+            }
+        }
+        catch (err) {
+            meta.errors.push(`KEGG: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        meta.errors.push('KEGG: skipped (no NCBI Gene ID to map from)');
+    }
+    const profileData = {
+        symbol,
+        name: ncbiData?.name ?? '',
+        summary: ncbiData?.summary ?? '',
+        chromosome: ncbiData?.chromosome ?? '',
+        location: ncbiData?.location ?? '',
+        function: uniprotData?.function ?? '',
+        subcellularLocation: uniprotData?.subcellularLocation ?? '',
+        pathways: (keggData?.pathways ?? []).map(p => ({ ...p, source: 'KEGG' })),
+        goTerms: uniprotData?.goTerms ?? [],
+        interactions,
+        diseases: (keggData?.diseases ?? []).map(d => ({ ...d, source: 'KEGG' })),
+    };
+    const ids = {};
+    if (ncbiData?.geneId)
+        ids.ncbiGeneId = ncbiData.geneId;
+    if (uniprotData?.accession)
+        ids.uniprotAccession = uniprotData.accession;
+    if (keggData?.keggId)
+        ids.keggId = keggData.keggId;
+    if (uniprotData?.ensemblGeneId)
+        ids.ensemblGeneId = uniprotData.ensemblGeneId;
+    return wrapResult(profileData, {
+        ids,
+        sources: meta.sources,
+        warnings: meta.errors,
+        organism: organismName,
+        query: symbol,
+    });
+}
+cli({
+    site: 'aggregate',
+    name: 'gene-profile',
+    description: 'Complete gene profile from NCBI + UniProt + KEGG + STRING',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 60,
+    args: [
+        { name: 'genes', positional: true, required: true, help: 'Gene symbol(s), comma-separated (e.g. TP53 or TP53,BRCA1,EGFR)' },
+        { name: 'organism', default: 'human', help: 'Organism (e.g. human, mouse, 9606)' },
+    ],
+    columns: ['symbol', 'name', 'organism', 'pathways', 'goTerms', 'interactions'],
+    func: async (_ctx, args) => {
+        const genes = String(args.genes).split(',').map(s => s.trim()).filter(Boolean);
+        if (!genes.length) {
+            throw new CliError('ARGUMENT', 'At least one gene symbol is required');
+        }
+        const org = resolveOrganism(String(args.organism));
+        if (genes.length === 1) {
+            return await buildGeneProfile(genes[0], org.name, org.taxId, org.keggOrg);
+        }
+        // Batch: process genes sequentially to respect rate limits
+        const profiles = [];
+        for (const gene of genes) {
+            profiles.push(await buildGeneProfile(gene, org.name, org.taxId, org.keggOrg));
+        }
+        return profiles;
+    },
+});

package/dist/clis/aggregate/literature-brief.d.ts

@@ -0,0 +1,7 @@
+/**
+ * aggregate/literature-brief — PubMed literature summary for a topic.
+ *
+ * Fetches recent papers and returns structured data with abstracts,
+ * optimized for AI agent consumption and literature review tasks.
+ */
+export {};

package/dist/clis/aggregate/literature-brief.js

@@ -0,0 +1,79 @@
+/**
+ * aggregate/literature-brief — PubMed literature summary for a topic.
+ *
+ * Fetches recent papers and returns structured data with abstracts,
+ * optimized for AI agent consumption and literature review tasks.
+ */
+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';
+cli({
+    site: 'aggregate',
+    name: 'literature-brief',
+    description: 'Literature summary with abstracts for a research topic',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 60,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search query (e.g. "TP53 immunotherapy", "CRISPR cancer")' },
+        { name: 'limit', type: 'int', default: 10, help: 'Number of papers (1-50)' },
+        { name: 'sort', default: 'relevance', choices: ['relevance', 'date'], help: 'Sort order' },
+        { name: 'years', type: 'int', default: 5, help: 'Limit to last N years' },
+    ],
+    columns: ['pmid', 'title', 'journal', 'year', 'abstract'],
+    func: async (_ctx, args) => {
+        const query = String(args.query).trim();
+        if (!query)
+            throw new CliError('ARGUMENT', 'Search query is required');
+        const limit = Math.max(1, Math.min(Number(args.limit), 50));
+        const sort = String(args.sort) === 'date' ? 'pub_date' : 'relevance';
+        const years = Math.max(1, Math.min(Number(args.years), 20));
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        const warnings = [];
+        // Build date-restricted query
+        const dateQuery = `${query} AND "last ${years} years"[PDat]`;
+        // Step 1: esearch
+        const searchResult = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+            db: 'pubmed',
+            term: dateQuery,
+            retmax: String(limit),
+            sort,
+            retmode: 'json',
+        }));
+        const esearch = searchResult?.esearchresult;
+        const pmids = esearch?.idlist ?? [];
+        const totalCount = Number(esearch?.count ?? 0);
+        if (!pmids.length) {
+            throw new CliError('NOT_FOUND', `No papers found for "${query}"`, 'Try broader terms or increase --years');
+        }
+        // Step 2: efetch with full abstracts
+        const xmlData = await ncbiCtx.fetchXml(buildEutilsUrl('efetch.fcgi', {
+            db: 'pubmed',
+            id: pmids.join(','),
+            rettype: 'xml',
+        }));
+        const articles = parsePubmedArticles(xmlData);
+        if (!articles.length) {
+            throw new CliError('PARSE_ERROR', 'Failed to parse PubMed response');
+        }
+        const papers = articles.map(a => ({
+            pmid: a.pmid,
+            title: a.title,
+            authors: a.authors,
+            journal: a.journal,
+            year: a.year,
+            doi: a.doi,
+            abstract: a.abstract,
+        }));
+        return wrapResult({ papers, totalAvailable: totalCount }, {
+            sources: ['PubMed'],
+            warnings,
+            query,
+            ids: { totalPmids: String(totalCount) },
+        });
+    },
+});

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

@@ -0,0 +1,11 @@
+/**
+ * aggregate/variant-dossier — Comprehensive variant interpretation report.
+ *
+ * Cross-queries:
+ *   - NCBI dbSNP (basic variant info)
+ *   - ClinVar (clinical significance)
+ *   - Ensembl VEP (functional consequence prediction)
+ *
+ * Accepts rsID (rs334), HGVS notation, or gene:variant format.
+ */
+export {};

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

@@ -0,0 +1,161 @@
+/**
+ * aggregate/variant-dossier — Comprehensive variant interpretation report.
+ *
+ * Cross-queries:
+ *   - NCBI dbSNP (basic variant info)
+ *   - ClinVar (clinical significance)
+ *   - Ensembl VEP (functional consequence prediction)
+ *
+ * Accepts rsID (rs334), HGVS notation, or gene:variant format.
+ */
+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 { buildEnsemblUrl } from '../../databases/ensembl.js';
+cli({
+    site: 'aggregate',
+    name: 'variant-dossier',
+    description: 'Comprehensive variant interpretation (dbSNP + ClinVar + VEP)',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 60,
+    args: [
+        { name: 'variant', positional: true, required: true, help: 'Variant ID: rsID (rs334), HGVS, or genomic coordinate' },
+    ],
+    columns: ['variant', 'gene', 'consequence', 'clinicalSignificance', 'condition'],
+    func: async (_ctx, args) => {
+        const variant = String(args.variant).trim();
+        if (!variant)
+            throw new CliError('ARGUMENT', 'Variant ID is required');
+        const sources = [];
+        const warnings = [];
+        const ids = {};
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        const ensemblCtx = createHttpContextForDatabase('ensembl');
+        // Determine if input is rsID
+        const isRsId = /^rs\d+$/i.test(variant);
+        if (isRsId)
+            ids.rsId = variant;
+        // Parallel queries
+        const [snpResult, clinvarResult, vepResult] = await Promise.allSettled([
+            // dbSNP lookup
+            isRsId ? (async () => {
+                const data = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                    db: 'snp', id: variant.replace(/^rs/i, ''), retmode: 'json',
+                }));
+                const result = data?.result;
+                const snpId = variant.replace(/^rs/i, '');
+                const entry = result?.[snpId];
+                if (!entry)
+                    return null;
+                return {
+                    rsid: `rs${snpId}`,
+                    gene: String((Array.isArray(entry.genes) && entry.genes.length > 0) ? entry.genes[0].name ?? '' : ''),
+                    chromosome: String(entry.chr ?? ''),
+                    position: String(entry.chrpos ?? ''),
+                    alleles: String(entry.docsum ?? ''),
+                    maf: String(entry.global_maf ?? ''),
+                };
+            })() : Promise.resolve(null),
+            // ClinVar search
+            isRsId ? (async () => {
+                const sr = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                    db: 'clinvar', term: `${variant}[Variant ID]`, retmax: '5', retmode: 'json',
+                }));
+                const cvIds = sr?.esearchresult?.idlist ?? [];
+                if (!cvIds.length)
+                    return [];
+                const summ = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                    db: 'clinvar', id: cvIds.join(','), retmode: 'json',
+                }));
+                const resultObj = summ?.result;
+                const uids = resultObj?.uids ?? [];
+                return uids.map(uid => {
+                    const item = (resultObj?.[uid] ?? {});
+                    const sig = typeof item.clinical_significance === 'object'
+                        ? String(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: sig,
+                        condition: traits,
+                        accession: String(item.accession ?? ''),
+                    };
+                });
+            })() : Promise.resolve([]),
+            // Ensembl VEP
+            (async () => {
+                const vepPath = isRsId
+                    ? `/vep/human/id/${variant}`
+                    : `/vep/human/hgvs/${encodeURIComponent(variant)}`;
+                const data = await ensemblCtx.fetchJson(buildEnsemblUrl(vepPath, { canonical: '1', hgvs: '1', protein: '1' }));
+                if (!Array.isArray(data) || !data.length)
+                    return [];
+                const entry = data[0];
+                const tc = (entry.transcript_consequences ?? []);
+                // Pick canonical transcript or first
+                const sorted = [...tc].sort((a, b) => (a.canonical ? -1 : 0) - (b.canonical ? -1 : 0));
+                return sorted.slice(0, 5).map(t => ({
+                    gene: String(t.gene_symbol ?? ''),
+                    transcript: String(t.transcript_id ?? ''),
+                    consequence: (t.consequence_terms ?? []).join(', '),
+                    impact: String(t.impact ?? ''),
+                    aminoAcids: String(t.amino_acids ?? ''),
+                    codons: String(t.codons ?? ''),
+                    biotype: String(t.biotype ?? ''),
+                    canonical: Boolean(t.canonical),
+                }));
+            })(),
+        ]);
+        // Assemble
+        let snpData = null;
+        if (snpResult.status === 'fulfilled' && snpResult.value) {
+            snpData = snpResult.value;
+            sources.push('dbSNP');
+            if (snpData.gene)
+                ids.gene = snpData.gene;
+        }
+        else if (snpResult.status === 'rejected') {
+            warnings.push(`dbSNP: ${snpResult.reason}`);
+        }
+        const clinvar = clinvarResult.status === 'fulfilled' ? clinvarResult.value : [];
+        if (clinvar.length)
+            sources.push('ClinVar');
+        else if (clinvarResult.status === 'rejected') {
+            warnings.push(`ClinVar: ${clinvarResult.reason}`);
+        }
+        const vep = vepResult.status === 'fulfilled' ? vepResult.value : [];
+        if (vep.length)
+            sources.push('Ensembl VEP');
+        else if (vepResult.status === 'rejected') {
+            warnings.push(`Ensembl VEP: ${vepResult.reason}`);
+        }
+        if (!snpData && !clinvar.length && !vep.length) {
+            throw new CliError('NOT_FOUND', `No data found for variant "${variant}"`, 'Check the variant ID format (e.g. rs334, NM_000518.5:c.20A>T)');
+        }
+        const dossier = {
+            variant,
+            gene: snpData?.gene ?? vep[0]?.gene ?? '',
+            chromosome: snpData?.chromosome ?? '',
+            position: snpData?.position ?? '',
+            vepConsequences: vep,
+            clinicalVariants: clinvar,
+            dbsnp: snpData ? {
+                alleles: snpData.alleles,
+                maf: snpData.maf,
+            } : null,
+        };
+        return wrapResult(dossier, {
+            ids,
+            sources,
+            warnings,
+            query: variant,
+        });
+    },
+});

package/dist/clis/aggregate/variant-interpret.d.ts

@@ -0,0 +1,10 @@
+/**
+ * aggregate/variant-interpret — Variant interpretation with clinical context.
+ *
+ * Builds on variant-dossier by adding:
+ *   - UniProt protein function context for the affected gene
+ *   - Structured interpretation summary (pathogenicity, impact, recommendation)
+ *
+ * Cross-queries: dbSNP + ClinVar + Ensembl VEP + UniProt
+ */
+export {};