@yangfei_93sky/biocli 0.2.0

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

@@ -0,0 +1,210 @@
+/**
+ * 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
+ */
+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';
+import { buildUniprotUrl } from '../../databases/uniprot.js';
+// ── Impact severity mapping ──────────────────────────────────────────────────
+const IMPACT_SEVERITY = {
+    HIGH: 4,
+    MODERATE: 3,
+    LOW: 2,
+    MODIFIER: 1,
+};
+function interpretImpact(impact) {
+    switch (impact) {
+        case 'HIGH': return 'Likely damaging — causes protein truncation, loss of function, or frameshift';
+        case 'MODERATE': return 'Possibly damaging — amino acid change that may affect protein function';
+        case 'LOW': return 'Likely benign — synonymous or non-coding change with minimal functional impact';
+        case 'MODIFIER': return 'Uncertain — regulatory or non-coding region variant';
+        default: return 'Unknown impact';
+    }
+}
+cli({
+    site: 'aggregate',
+    name: 'variant-interpret',
+    description: 'Variant interpretation with clinical context (dbSNP + ClinVar + VEP + UniProt)',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 90,
+    args: [
+        { name: 'variant', positional: true, required: true, help: 'Variant ID: rsID (rs334), HGVS, or genomic coordinate' },
+    ],
+    columns: ['variant', 'gene', 'consequence', 'clinicalSignificance', 'interpretation'],
+    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');
+        const uniprotCtx = createHttpContextForDatabase('uniprot');
+        const isRsId = /^rs\d+$/i.test(variant);
+        if (isRsId)
+            ids.rsId = variant;
+        // Phase 1: Parallel queries (dbSNP + ClinVar + VEP)
+        const [snpResult, clinvarResult, vepResult] = await Promise.allSettled([
+            // dbSNP
+            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 ?? ''),
+                    clinicalSignificance: Array.isArray(entry.clinical_significance)
+                        ? entry.clinical_significance.join(', ')
+                        : String(entry.clinical_significance ?? ''),
+                };
+            })() : Promise.resolve(null),
+            // ClinVar
+            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 { 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 ?? []);
+                const sorted = [...tc].sort((a, b) => (IMPACT_SEVERITY[String(b.impact ?? '')] ?? 0) - (IMPACT_SEVERITY[String(a.impact ?? '')] ?? 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 ?? ''),
+                    biotype: String(t.biotype ?? ''),
+                    canonical: Boolean(t.canonical),
+                }));
+            })(),
+        ]);
+        // Extract results
+        const snpData = snpResult.status === 'fulfilled' ? snpResult.value : null;
+        if (snpData) {
+            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}`);
+        const geneName = snpData?.gene ?? vep[0]?.gene ?? '';
+        // Phase 2: UniProt lookup for gene context (if we have a gene name)
+        let proteinFunction = '';
+        if (geneName) {
+            try {
+                const searchData = await uniprotCtx.fetchJson(buildUniprotUrl('/uniprotkb/search', {
+                    query: `gene_exact:${geneName} AND organism_id:9606`,
+                    fields: 'accession,cc_function',
+                    format: 'json',
+                    size: '1',
+                }));
+                const results = (searchData?.results ?? []);
+                if (results.length > 0) {
+                    sources.push('UniProt');
+                    const entry = results[0];
+                    ids.uniprotAccession = String(entry.primaryAccession ?? '');
+                    const comments = (entry.comments ?? []);
+                    const funcComment = comments.find(c => c.commentType === 'FUNCTION');
+                    const texts = (funcComment?.texts ?? []);
+                    proteinFunction = texts.map(t => String(t.value ?? '')).join(' ');
+                }
+            }
+            catch (err) {
+                warnings.push(`UniProt: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        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)');
+        }
+        // Build interpretation
+        const topVep = vep[0];
+        const topClinvar = clinvar[0];
+        const highestImpact = topVep?.impact ?? 'Unknown';
+        const clinSig = topClinvar?.significance ?? snpData?.clinicalSignificance ?? 'Not reported';
+        const interpretation = {
+            clinicalSignificance: clinSig,
+            functionalImpact: interpretImpact(highestImpact),
+            consequence: topVep?.consequence ?? 'Unknown',
+            affectedGene: geneName,
+            proteinFunction: proteinFunction || 'No function annotation available',
+            conditions: clinvar.map(c => c.condition).filter(Boolean),
+            evidenceSources: sources,
+            recommendation: clinSig.toLowerCase().includes('pathogenic')
+                ? 'This variant has clinical significance. Consider genetic counseling and further clinical evaluation.'
+                : clinSig.toLowerCase().includes('benign')
+                    ? 'This variant is classified as benign. No clinical action typically required.'
+                    : 'Clinical significance is uncertain. Consider functional studies or additional evidence.',
+        };
+        return wrapResult({
+            variant,
+            gene: geneName,
+            chromosome: snpData?.chromosome ?? '',
+            position: snpData?.position ?? '',
+            interpretation,
+            vepConsequences: vep,
+            clinicalVariants: clinvar,
+            dbsnp: snpData ? { alleles: snpData.alleles } : null,
+        }, {
+            ids,
+            sources,
+            warnings,
+            query: variant,
+        });
+    },
+});

package/dist/clis/aggregate/workflow-prepare.d.ts

@@ -0,0 +1,12 @@
+/**
+ * aggregate/workflow-prepare — Prepare a research-ready working directory.
+ *
+ * Takes a user-selected dataset (from workflow-scout) and:
+ *   1. Downloads GEO supplementary files or SRA metadata
+ *   2. Fetches gene annotations (NCBI Gene + UniProt)
+ *   3. Fetches pathway context (KEGG)
+ *   4. Generates a structured manifest.json
+ *
+ * Output: a self-contained directory with data + annotations + manifest.
+ */
+export {};

package/dist/clis/aggregate/workflow-prepare.js

@@ -0,0 +1,228 @@
+/**
+ * aggregate/workflow-prepare — Prepare a research-ready working directory.
+ *
+ * Takes a user-selected dataset (from workflow-scout) and:
+ *   1. Downloads GEO supplementary files or SRA metadata
+ *   2. Fetches gene annotations (NCBI Gene + UniProt)
+ *   3. Fetches pathway context (KEGG)
+ *   4. Generates a structured manifest.json
+ *
+ * Output: a self-contained directory with data + annotations + manifest.
+ */
+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 } from '../../databases/kegg.js';
+import { mkdirSync, existsSync, writeFileSync, createWriteStream } from 'node:fs';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+cli({
+    site: 'aggregate',
+    name: 'workflow-prepare',
+    description: 'Prepare a research-ready directory from a selected dataset',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 300,
+    args: [
+        { name: 'dataset', positional: true, required: true, help: 'GEO accession (GSE*) or SRA accession (SRR*)' },
+        { name: 'gene', help: 'Focus gene symbol(s), comma-separated (e.g. TP53,BRCA1)' },
+        { name: 'outdir', required: true, help: 'Output directory for the prepared workspace' },
+        { name: 'skip-download', type: 'boolean', default: false, help: 'Skip data download, only fetch annotations' },
+    ],
+    columns: ['step', 'status', 'detail'],
+    func: async (_ctx, args) => {
+        const dataset = String(args.dataset).trim().toUpperCase();
+        const geneInput = args.gene ? String(args.gene) : undefined;
+        const genes = geneInput ? geneInput.split(',').map(s => s.trim()).filter(Boolean) : [];
+        const outdir = String(args.outdir);
+        const skipDownload = Boolean(args['skip-download']);
+        if (!dataset)
+            throw new CliError('ARGUMENT', 'Dataset accession is required');
+        const isGEO = /^GSE\d+$/.test(dataset);
+        const isSRA = /^[SDE]RR\d+$/i.test(dataset);
+        if (!isGEO && !isSRA) {
+            throw new CliError('ARGUMENT', `Unsupported dataset type: "${dataset}"`, 'Use a GSE accession (GEO) or SRR/ERR/DRR accession (SRA)');
+        }
+        // Create output directory structure
+        const dataDir = join(outdir, 'data');
+        const annotDir = join(outdir, 'annotations');
+        for (const dir of [outdir, dataDir, annotDir]) {
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+        }
+        const sources = [];
+        const warnings = [];
+        const steps = [];
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        // ── Step 1: Download dataset ────────────────────────────────────────
+        if (!skipDownload) {
+            if (isGEO) {
+                try {
+                    const prefix = dataset.slice(0, -3) + 'nnn';
+                    const supplUrl = `https://ftp.ncbi.nlm.nih.gov/geo/series/${prefix}/${dataset}/suppl/`;
+                    const html = await ncbiCtx.fetchText(supplUrl);
+                    // Parse file list
+                    const linkRegex = /<a\s+href="([^"]+)">[^<]+<\/a>\s+[\d-]+\s+[\d:]+\s+([\d.]+[KMG]?)/gi;
+                    const files = [];
+                    let match;
+                    while ((match = linkRegex.exec(html)) !== null) {
+                        if (match[1] !== '../' && !match[1].endsWith('/')) {
+                            files.push({ name: match[1], size: match[2] });
+                        }
+                    }
+                    let downloaded = 0;
+                    for (const file of files) {
+                        try {
+                            const resp = await fetch(`${supplUrl}${file.name}`);
+                            if (resp.ok && resp.body) {
+                                const ws = createWriteStream(join(dataDir, file.name));
+                                await pipeline(Readable.fromWeb(resp.body), ws);
+                                downloaded++;
+                            }
+                        }
+                        catch (err) {
+                            warnings.push(`Download ${file.name}: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                    steps.push({ step: 'download', status: 'done', detail: `${downloaded}/${files.length} GEO files → ${dataDir}` });
+                    sources.push('GEO');
+                }
+                catch (err) {
+                    steps.push({ step: 'download', status: 'failed', detail: String(err instanceof Error ? err.message : err) });
+                    warnings.push(`GEO download: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                // SRA: just save metadata, actual FASTQ download is too large for prepare
+                steps.push({ step: 'download', status: 'skipped', detail: 'SRA FASTQ download too large for prepare — use `biocli sra download` separately' });
+            }
+        }
+        else {
+            steps.push({ step: 'download', status: 'skipped', detail: '--skip-download flag' });
+        }
+        // ── Step 2: Gene annotations ────────────────────────────────────────
+        if (genes.length > 0) {
+            const geneAnnotations = [];
+            for (const gene of genes) {
+                try {
+                    // NCBI Gene search
+                    const searchResult = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                        db: 'gene', term: `${gene}[Gene Name] AND Homo sapiens[Organism]`, retmax: '1', retmode: 'json',
+                    }));
+                    const geneIds = searchResult?.esearchresult?.idlist ?? [];
+                    if (geneIds.length > 0) {
+                        const summaryResult = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                            db: 'gene', id: geneIds[0], retmode: 'json',
+                        }));
+                        const resultObj = summaryResult?.result;
+                        const entry = resultObj?.[geneIds[0]];
+                        const annotation = {
+                            symbol: gene,
+                            ncbiGeneId: geneIds[0],
+                            name: entry?.description ?? '',
+                            chromosome: entry?.chromosome ?? '',
+                            summary: entry?.summary ?? '',
+                        };
+                        // UniProt protein info — use reviewed:true + exact symbol match (same as gene-profile)
+                        try {
+                            const uniprotCtx = createHttpContextForDatabase('uniprot');
+                            const upResult = await uniprotCtx.fetchJson(buildUniprotUrl('/uniprotkb/search', {
+                                query: `gene:${gene} AND organism_id:9606 AND reviewed:true`,
+                                format: 'json',
+                                size: '5',
+                            }));
+                            const upEntries = (upResult?.results ?? []);
+                            if (upEntries.length > 0) {
+                                // Find exact gene name match among candidates
+                                const getGeneName = (e) => {
+                                    const gs = e.genes;
+                                    const gn = gs?.[0];
+                                    const name = gn?.geneName;
+                                    return String(name?.value ?? '');
+                                };
+                                const exactMatch = upEntries.find(e => getGeneName(e).toUpperCase() === gene.toUpperCase());
+                                const best = exactMatch ?? upEntries[0];
+                                annotation.uniprotAccession = best.primaryAccession ?? '';
+                                sources.push('UniProt');
+                            }
+                        }
+                        catch { /* non-fatal */ }
+                        geneAnnotations.push(annotation);
+                        sources.push('NCBI Gene');
+                    }
+                }
+                catch (err) {
+                    warnings.push(`Gene ${gene}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (geneAnnotations.length > 0) {
+                writeFileSync(join(annotDir, 'genes.json'), JSON.stringify(geneAnnotations, null, 2));
+                steps.push({ step: 'gene-annotations', status: 'done', detail: `${geneAnnotations.length} gene(s) → annotations/genes.json` });
+            }
+            // KEGG pathways for genes — use NCBI Gene IDs (stable) instead of symbols
+            try {
+                const keggCtx = createHttpContextForDatabase('kegg');
+                const allPathways = [];
+                for (const annot of geneAnnotations) {
+                    const geneId = annot.ncbiGeneId;
+                    const symbol = annot.symbol;
+                    if (!geneId)
+                        continue;
+                    try {
+                        const linkText = await keggCtx.fetchText(buildKeggUrl(`/link/pathway/hsa:${geneId}`));
+                        if (linkText && linkText.trim()) {
+                            const links = parseKeggTsv(linkText);
+                            allPathways.push(...links.map(l => ({ gene: symbol, ncbiGeneId: geneId, pathway: l.value })));
+                        }
+                    }
+                    catch {
+                        warnings.push(`KEGG pathway for ${symbol} (hsa:${geneId}): no results`);
+                    }
+                }
+                if (allPathways.length > 0) {
+                    writeFileSync(join(annotDir, 'pathways.json'), JSON.stringify(allPathways, null, 2));
+                    steps.push({ step: 'pathways', status: 'done', detail: `${allPathways.length} pathway links → annotations/pathways.json` });
+                    sources.push('KEGG');
+                }
+            }
+            catch (err) {
+                warnings.push(`KEGG pathways: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            steps.push({ step: 'gene-annotations', status: 'skipped', detail: 'No --gene specified' });
+        }
+        // ── Step 3: Generate manifest ───────────────────────────────────────
+        const manifest = {
+            biocliVersion: '0.2.0',
+            createdAt: new Date().toISOString(),
+            dataset,
+            genes,
+            organism: 'Homo sapiens',
+            sources: [...new Set(sources)],
+            warnings,
+            directories: {
+                data: 'data/',
+                annotations: 'annotations/',
+            },
+            steps,
+        };
+        steps.push({ step: 'manifest', status: 'done', detail: `manifest.json → ${outdir}` });
+        writeFileSync(join(outdir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        return wrapResult({
+            outdir,
+            dataset,
+            steps,
+        }, {
+            ids: { dataset, ...(genes.length === 1 ? { gene: genes[0] } : {}) },
+            sources: [...new Set(sources)],
+            warnings,
+            query: dataset,
+        });
+    },
+});

package/dist/clis/aggregate/workflow-scout.d.ts

@@ -0,0 +1,13 @@
+/**
+ * aggregate/workflow-scout — Scout datasets for a research question.
+ *
+ * Searches GEO and SRA for relevant datasets based on gene + disease/topic,
+ * ranks candidates, and provides structured recommendations for the user
+ * to select before downloading with `workflow prepare`.
+ *
+ * Cross-queries:
+ *   - GEO (datasets with expression data)
+ *   - SRA (sequencing runs)
+ *   - NCBI Gene (gene context for query refinement)
+ */
+export {};

package/dist/clis/aggregate/workflow-scout.js

@@ -0,0 +1,175 @@
+/**
+ * aggregate/workflow-scout — Scout datasets for a research question.
+ *
+ * Searches GEO and SRA for relevant datasets based on gene + disease/topic,
+ * ranks candidates, and provides structured recommendations for the user
+ * to select before downloading with `workflow prepare`.
+ *
+ * Cross-queries:
+ *   - GEO (datasets with expression data)
+ *   - SRA (sequencing runs)
+ *   - NCBI Gene (gene context for query refinement)
+ */
+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';
+cli({
+    site: 'aggregate',
+    name: 'workflow-scout',
+    description: 'Scout GEO/SRA datasets for a research question',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 60,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Research topic (e.g. "TP53 breast cancer RNA-seq")' },
+        { name: 'gene', help: 'Focus gene symbol (refines search)' },
+        { name: 'organism', default: 'Homo sapiens', help: 'Organism filter' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max candidates per source' },
+        { name: 'type', default: 'gse', choices: ['gse', 'gds', 'all'], help: 'GEO entry type filter' },
+    ],
+    columns: ['rank', 'accession', 'title', 'type', 'samples', 'date', 'source'],
+    func: async (_ctx, args) => {
+        const query = String(args.query).trim();
+        const gene = args.gene ? String(args.gene).trim() : undefined;
+        const organism = String(args.organism);
+        const limit = Math.max(1, Math.min(Number(args.limit), 50));
+        const typeFilter = String(args.type).toUpperCase();
+        if (!query)
+            throw new CliError('ARGUMENT', 'Search query is required');
+        const sources = [];
+        const warnings = [];
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        // Build refined search terms
+        const geneClause = gene ? `${gene}[Gene Name] AND ` : '';
+        const orgClause = organism ? `${organism}[Organism] AND ` : '';
+        // ── GEO search ──────────────────────────────────────────────────────
+        const geoCandidates = [];
+        try {
+            const geoTerm = typeFilter === 'ALL'
+                ? `${geneClause}${orgClause}${query}`
+                : `${geneClause}${orgClause}${query} AND ${typeFilter}[Entry Type]`;
+            const searchResult = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                db: 'gds',
+                term: geoTerm,
+                retmax: String(limit),
+                retmode: 'json',
+                sort: 'relevance',
+            }));
+            const esearch = searchResult?.esearchresult;
+            const ids = esearch?.idlist ?? [];
+            if (ids.length > 0) {
+                const summaryResult = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                    db: 'gds',
+                    id: ids.join(','),
+                    retmode: 'json',
+                }));
+                const resultObj = summaryResult?.result;
+                const uids = resultObj?.uids ?? [];
+                for (let i = 0; i < uids.length; i++) {
+                    const item = (resultObj?.[uids[i]] ?? {});
+                    geoCandidates.push({
+                        rank: i + 1,
+                        accession: String(item.accession ?? `GDS${uids[i]}`),
+                        title: String(item.title ?? ''),
+                        organism: String(item.taxon ?? ''),
+                        type: String(item.entrytype ?? ''),
+                        samples: Number(item.n_samples ?? 0),
+                        date: String(item.pdat ?? ''),
+                        relevance: gene
+                            ? (String(item.title ?? '').toLowerCase().includes(gene.toLowerCase()) ? 'gene in title' : 'keyword match')
+                            : 'keyword match',
+                        source: 'GEO',
+                    });
+                }
+                sources.push('GEO');
+            }
+        }
+        catch (err) {
+            warnings.push(`GEO search failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ── SRA search ──────────────────────────────────────────────────────
+        const sraCandidates = [];
+        try {
+            const sraTerm = `${geneClause}${orgClause}${query}`;
+            const searchResult = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                db: 'sra',
+                term: sraTerm,
+                retmax: String(limit),
+                retmode: 'json',
+                sort: 'relevance',
+            }));
+            const esearch = searchResult?.esearchresult;
+            const ids = esearch?.idlist ?? [];
+            if (ids.length > 0) {
+                const summaryResult = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                    db: 'sra',
+                    id: ids.join(','),
+                    retmode: 'json',
+                }));
+                const resultObj = summaryResult?.result;
+                const uids = resultObj?.uids ?? [];
+                for (let i = 0; i < uids.length; i++) {
+                    const item = (resultObj?.[uids[i]] ?? {});
+                    const expXml = String(item.expxml ?? '');
+                    const runsXml = String(item.runs ?? '');
+                    // Extract from embedded XML
+                    const titleMatch = expXml.match(/<Title>([^<]*)<\/Title>/);
+                    const orgMatch = expXml.match(/taxname="([^"]*)"/);
+                    const accMatch = runsXml.match(/acc="([^"]*)"/);
+                    const strategyMatch = expXml.match(/<Library_strategy>([^<]*)<\/Library_strategy>/);
+                    sraCandidates.push({
+                        rank: i + 1,
+                        accession: accMatch?.[1] ?? `SRA${uids[i]}`,
+                        title: (titleMatch?.[1] ?? '').slice(0, 100),
+                        organism: orgMatch?.[1] ?? '',
+                        type: strategyMatch?.[1] ?? 'SRA',
+                        samples: Number(item.total_runs ?? 1),
+                        date: String(item.createdate ?? ''),
+                        relevance: 'keyword match',
+                        source: 'SRA',
+                    });
+                }
+                sources.push('SRA');
+            }
+        }
+        catch (err) {
+            warnings.push(`SRA search failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ── Merge and rank ──────────────────────────────────────────────────
+        const allCandidates = [...geoCandidates, ...sraCandidates];
+        if (!allCandidates.length) {
+            throw new CliError('NOT_FOUND', `No datasets found for "${query}"`, 'Try broader search terms, or remove --gene/--organism filters');
+        }
+        // Re-rank: prefer more samples, gene-in-title, recent date
+        allCandidates.sort((a, b) => {
+            // Gene in title gets priority
+            const aGeneBoost = a.relevance === 'gene in title' ? 1000 : 0;
+            const bGeneBoost = b.relevance === 'gene in title' ? 1000 : 0;
+            // More samples = better
+            const score = (bGeneBoost + b.samples) - (aGeneBoost + a.samples);
+            if (score !== 0)
+                return score;
+            // Tie-break by date (newer first)
+            return b.date.localeCompare(a.date);
+        });
+        // Re-assign ranks
+        allCandidates.forEach((c, i) => { c.rank = i + 1; });
+        const nextSteps = allCandidates.slice(0, 3).map(c => c.source === 'GEO'
+            ? `biocli geo download ${c.accession} --list-only`
+            : `biocli sra download ${c.accession} --dry-run`);
+        return wrapResult({
+            candidates: allCandidates,
+            summary: `Found ${geoCandidates.length} GEO + ${sraCandidates.length} SRA candidates for "${query}"`,
+            nextSteps,
+        }, {
+            ids: gene ? { gene } : {},
+            sources,
+            warnings,
+            query,
+            organism,
+        });
+    },
+});

package/dist/clis/clinvar/search.d.ts

@@ -0,0 +1,8 @@
+/**
+ * clinvar/search — Search ClinVar clinical variants.
+ *
+ * Uses the two-step esearch + esummary pattern:
+ *   1. esearch to retrieve matching ClinVar IDs
+ *   2. esummary (JSON) to get variant metadata
+ */
+export {};