@yangfei_93sky/biocli 0.2.0

package/dist/clis/clinvar/search.js

@@ -0,0 +1,61 @@
+/**
+ * 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
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { withMeta } from '../../types.js';
+cli({
+    site: 'clinvar',
+    name: 'search',
+    description: 'Search ClinVar clinical variants',
+    database: 'clinvar',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search query (e.g. "BRCA1", "rs80357906", "breast cancer")' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max results (1-200)' },
+    ],
+    columns: ['uid', 'title', 'gene', 'significance', 'condition', 'accession'],
+    func: async (ctx, args) => {
+        const limit = Math.max(1, Math.min(Number(args.limit), 200));
+        const query = String(args.query);
+        // Step 1: esearch to get ClinVar IDs
+        const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+            db: 'clinvar', term: query, retmax: String(limit), retmode: 'json',
+        }));
+        const ids = searchResult?.esearchresult?.idlist ?? [];
+        const totalCount = Number(searchResult?.esearchresult?.count ?? 0);
+        if (!ids.length)
+            throw new CliError('NOT_FOUND', 'No ClinVar entries found');
+        // Step 2: esummary to get variant details
+        const summary = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+            db: 'clinvar', id: ids.join(','), retmode: 'json',
+        }));
+        const uids = summary?.result?.uids ?? [];
+        const rows = uids.map(uid => {
+            const item = summary.result[uid] ?? {};
+            // ClinVar esummary has: title, clinical_significance, genes (array of {symbol}),
+            // trait_set (array of {trait_name}), accession, variation_set
+            const genes = Array.isArray(item.genes) ? item.genes.map((g) => g.symbol).join(', ') : '';
+            const significance = typeof item.clinical_significance === 'object'
+                ? item.clinical_significance?.description ?? ''
+                : String(item.clinical_significance ?? '');
+            const conditions = Array.isArray(item.trait_set)
+                ? item.trait_set.map((t) => t.trait_name).join('; ')
+                : '';
+            return {
+                uid,
+                title: item.title ?? '',
+                gene: genes,
+                significance,
+                condition: conditions.slice(0, 60) + (conditions.length > 60 ? '...' : ''),
+                accession: item.accession ?? '',
+            };
+        });
+        return withMeta(rows, { totalCount, query });
+    },
+});

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

@@ -0,0 +1,7 @@
+/**
+ * clinvar/variant — Get ClinVar variant details by ID.
+ *
+ * Accepts a ClinVar variation ID (numeric) or accession (VCV*),
+ * uses esearch + esummary (JSON) to retrieve detailed variant metadata.
+ */
+export {};

package/dist/clis/clinvar/variant.js

@@ -0,0 +1,53 @@
+/**
+ * clinvar/variant — Get ClinVar variant details by ID.
+ *
+ * Accepts a ClinVar variation ID (numeric) or accession (VCV*),
+ * uses esearch + esummary (JSON) to retrieve detailed variant metadata.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+cli({
+    site: 'clinvar',
+    name: 'variant',
+    description: 'Get ClinVar variant details by ID',
+    database: 'clinvar',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'ClinVar variation ID or accession (e.g. 37722, VCV000037722)' },
+    ],
+    columns: ['uid', 'title', 'gene', 'significance', 'condition', 'accession', 'type', 'assembly'],
+    func: async (ctx, args) => {
+        const query = String(args.id);
+        // Try searching by ID or accession
+        const searchTerm = /^\d+$/.test(query) ? `${query}[VariationID]` : `${query}[Accession]`;
+        const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+            db: 'clinvar', term: searchTerm, retmode: 'json',
+        }));
+        const ids = searchResult?.esearchresult?.idlist ?? [];
+        if (!ids.length)
+            throw new CliError('NOT_FOUND', `ClinVar entry ${query} not found`);
+        const summary = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+            db: 'clinvar', id: ids[0], retmode: 'json',
+        }));
+        const item = summary?.result?.[ids[0]] ?? {};
+        const genes = Array.isArray(item.genes) ? item.genes.map((g) => g.symbol).join(', ') : '';
+        const significance = typeof item.clinical_significance === 'object'
+            ? item.clinical_significance?.description ?? ''
+            : String(item.clinical_significance ?? '');
+        const conditions = Array.isArray(item.trait_set)
+            ? item.trait_set.map((t) => t.trait_name).join('; ')
+            : '';
+        const varType = item.obj_type ?? item.variation_type ?? '';
+        return [{
+                uid: ids[0],
+                title: item.title ?? '',
+                gene: genes,
+                significance,
+                condition: conditions,
+                accession: item.accession ?? '',
+                type: varType,
+                assembly: item.assembly ?? '',
+            }];
+    },
+});

package/dist/clis/enrichr/analyze.d.ts

@@ -0,0 +1,7 @@
+/**
+ * enrichr/analyze — Run gene set enrichment analysis via Enrichr.
+ *
+ * 2-step workflow: submits a gene list, then retrieves enrichment results
+ * for the specified gene set library.
+ */
+export {};

package/dist/clis/enrichr/analyze.js

@@ -0,0 +1,48 @@
+/**
+ * enrichr/analyze — Run gene set enrichment analysis via Enrichr.
+ *
+ * 2-step workflow: submits a gene list, then retrieves enrichment results
+ * for the specified gene set library.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { submitGeneList, getEnrichment } from '../../databases/enrichr.js';
+import { withMeta } from '../../types.js';
+const DEFAULT_LIBRARY = 'KEGG_2021_Human';
+cli({
+    site: 'enrichr',
+    name: 'analyze',
+    description: 'Run gene set enrichment analysis',
+    database: 'enrichr',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'genes', positional: true, required: true, help: 'Comma-separated gene symbols (e.g. TP53,BRCA1,EGFR,MYC,CDK2)' },
+        { name: 'library', default: DEFAULT_LIBRARY, help: 'Gene set library (e.g. KEGG_2021_Human, GO_Biological_Process_2023, Reactome_2022)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max results to show (1-100)' },
+    ],
+    columns: ['rank', 'term', 'adjustedPValue', 'combinedScore', '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 for enrichment analysis', 'Example: biocli enrichr analyze TP53,BRCA1,EGFR,MYC,CDK2');
+        }
+        const library = String(args.library);
+        const limit = Math.max(1, Math.min(Number(args.limit), 100));
+        // Step 1: Submit gene list
+        const userListId = await submitGeneList(geneList);
+        // Step 2: Get enrichment results
+        const results = await getEnrichment(userListId, library);
+        if (!results.length) {
+            throw new CliError('NOT_FOUND', `No enrichment results from ${library}`, 'Try a different library or add more genes');
+        }
+        // Take top results by combined score
+        const rows = results.slice(0, limit).map(r => ({
+            rank: Number(r.rank),
+            term: String(r.term),
+            adjustedPValue: Number(r.adjustedPValue).toExponential(2),
+            combinedScore: Number(r.combinedScore).toFixed(1),
+            genes: String(r.genes),
+        }));
+        return withMeta(rows, { totalCount: results.length, query: geneList.join(',') });
+    },
+});

package/dist/clis/ensembl/lookup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ensembl/lookup — Look up a gene by symbol in Ensembl.
+ *
+ * Returns Ensembl gene ID, coordinates, biotype, and description.
+ */
+export {};

package/dist/clis/ensembl/lookup.js

@@ -0,0 +1,38 @@
+/**
+ * ensembl/lookup — Look up a gene by symbol in Ensembl.
+ *
+ * Returns Ensembl gene ID, coordinates, biotype, and description.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEnsemblUrl } from '../../databases/ensembl.js';
+cli({
+    site: 'ensembl',
+    name: 'lookup',
+    description: 'Look up a gene by symbol in Ensembl',
+    database: 'ensembl',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'symbol', positional: true, required: true, help: 'Gene symbol (e.g. BRCA2, TP53)' },
+        { name: 'species', default: 'homo_sapiens', help: 'Species name (e.g. homo_sapiens, mus_musculus)' },
+    ],
+    columns: ['ensemblId', 'symbol', 'biotype', 'chromosome', 'start', 'end', 'strand', 'description'],
+    func: async (ctx, args) => {
+        const symbol = String(args.symbol).trim();
+        const species = String(args.species).toLowerCase().replace(/\s+/g, '_');
+        const data = await ctx.fetchJson(buildEnsemblUrl(`/lookup/symbol/${species}/${symbol}`, { expand: '1' }));
+        if (!data || !data.id) {
+            throw new CliError('NOT_FOUND', `Gene "${symbol}" not found in Ensembl for ${species}`, 'Check the gene symbol and species');
+        }
+        return [{
+                ensemblId: String(data.id ?? ''),
+                symbol: String(data.display_name ?? ''),
+                biotype: String(data.biotype ?? ''),
+                chromosome: String(data.seq_region_name ?? ''),
+                start: Number(data.start ?? 0),
+                end: Number(data.end ?? 0),
+                strand: Number(data.strand ?? 0) === 1 ? '+' : '-',
+                description: String(data.description ?? '').replace(/\s*\[Source:.*\]/, ''),
+            }];
+    },
+});

package/dist/clis/ensembl/vep.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ensembl/vep — Variant Effect Predictor via Ensembl REST API.
+ *
+ * Predicts the functional consequences of variants using HGVS notation,
+ * rsID, or genomic coordinates.
+ */
+export {};

package/dist/clis/ensembl/vep.js

@@ -0,0 +1,86 @@
+/**
+ * ensembl/vep — Variant Effect Predictor via Ensembl REST API.
+ *
+ * Predicts the functional consequences of variants using HGVS notation,
+ * rsID, or genomic coordinates.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEnsemblUrl } from '../../databases/ensembl.js';
+cli({
+    site: 'ensembl',
+    name: 'vep',
+    description: 'Predict variant effects (VEP)',
+    database: 'ensembl',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'variant', positional: true, required: true, help: 'Variant in HGVS (e.g. "NM_000518.5:c.20A>T") or rsID (e.g. rs334)' },
+        { name: 'species', default: 'human', help: 'Species (default: human)' },
+    ],
+    columns: ['input', 'gene', 'consequence', 'impact', 'biotype', 'aminoAcid', 'codons'],
+    func: async (ctx, args) => {
+        const variant = String(args.variant).trim();
+        const species = String(args.species).toLowerCase();
+        // Determine endpoint based on input format
+        let url;
+        if (variant.startsWith('rs')) {
+            // rsID input
+            url = buildEnsemblUrl(`/vep/${species}/id/${variant}`, {
+                canonical: '1',
+                hgvs: '1',
+                protein: '1',
+            });
+        }
+        else {
+            // HGVS notation
+            url = buildEnsemblUrl(`/vep/${species}/hgvs/${encodeURIComponent(variant)}`, {
+                canonical: '1',
+                hgvs: '1',
+                protein: '1',
+            });
+        }
+        const data = await ctx.fetchJson(url);
+        if (!Array.isArray(data) || !data.length) {
+            throw new CliError('NOT_FOUND', `No VEP results for "${variant}"`, 'Check the variant notation');
+        }
+        const rows = [];
+        for (const entry of data) {
+            const transcriptConsequences = (entry.transcript_consequences ?? []);
+            const input = String(entry.input ?? entry.id ?? variant);
+            if (!transcriptConsequences.length) {
+                rows.push({
+                    input,
+                    gene: '',
+                    consequence: String(entry.most_severe_consequence ?? ''),
+                    impact: '',
+                    biotype: '',
+                    aminoAcid: '',
+                    codons: '',
+                });
+                continue;
+            }
+            // Show canonical transcript first, then others
+            const sorted = [...transcriptConsequences].sort((a, b) => {
+                if (a.canonical && !b.canonical)
+                    return -1;
+                if (!a.canonical && b.canonical)
+                    return 1;
+                return 0;
+            });
+            // Take top 5 most relevant consequences
+            for (const tc of sorted.slice(0, 5)) {
+                const consequences = (tc.consequence_terms ?? []);
+                rows.push({
+                    input,
+                    gene: String(tc.gene_symbol ?? ''),
+                    consequence: consequences.join(', '),
+                    impact: String(tc.impact ?? ''),
+                    biotype: String(tc.biotype ?? ''),
+                    aminoAcid: String(tc.amino_acids ?? ''),
+                    codons: String(tc.codons ?? ''),
+                });
+            }
+        }
+        return rows;
+    },
+});

package/dist/clis/ensembl/xrefs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ensembl/xrefs — Cross-references for a gene symbol in Ensembl.
+ *
+ * Returns linked IDs in HGNC, UniProt, RefSeq, OMIM, etc.
+ */
+export {};

package/dist/clis/ensembl/xrefs.js

@@ -0,0 +1,36 @@
+/**
+ * ensembl/xrefs — Cross-references for a gene symbol in Ensembl.
+ *
+ * Returns linked IDs in HGNC, UniProt, RefSeq, OMIM, etc.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEnsemblUrl } from '../../databases/ensembl.js';
+import { withMeta } from '../../types.js';
+cli({
+    site: 'ensembl',
+    name: 'xrefs',
+    description: 'Get cross-references for a gene',
+    database: 'ensembl',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'symbol', positional: true, required: true, help: 'Gene symbol (e.g. BRCA2)' },
+        { name: 'species', default: 'homo_sapiens', help: 'Species name' },
+    ],
+    columns: ['database', 'primaryId', 'displayId', 'description'],
+    func: async (ctx, args) => {
+        const symbol = String(args.symbol).trim();
+        const species = String(args.species).toLowerCase().replace(/\s+/g, '_');
+        const data = await ctx.fetchJson(buildEnsemblUrl(`/xrefs/symbol/${species}/${symbol}`));
+        if (!Array.isArray(data) || !data.length) {
+            throw new CliError('NOT_FOUND', `No cross-references found for "${symbol}"`, 'Check the gene symbol');
+        }
+        const rows = data.map(item => ({
+            database: String(item.dbname ?? ''),
+            primaryId: String(item.primary_id ?? ''),
+            displayId: String(item.display_id ?? ''),
+            description: String(item.description ?? '').replace(/\s*\[Source:.*\]/, ''),
+        }));
+        return withMeta(rows, { totalCount: rows.length, query: symbol });
+    },
+});

package/dist/clis/gene/fetch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * gene/fetch — Download gene sequence by NCBI Gene ID.
+ *
+ * Uses efetch to retrieve nucleotide or protein sequences in FASTA format.
+ * Workflow:
+ *   1. esummary to get gene metadata (for organism context)
+ *   2. elink to find linked nucleotide/protein records
+ *   3. efetch to download the sequence in requested format
+ */
+export {};

package/dist/clis/gene/fetch.js

@@ -0,0 +1,96 @@
+/**
+ * gene/fetch — Download gene sequence by NCBI Gene ID.
+ *
+ * Uses efetch to retrieve nucleotide or protein sequences in FASTA format.
+ * Workflow:
+ *   1. esummary to get gene metadata (for organism context)
+ *   2. elink to find linked nucleotide/protein records
+ *   3. efetch to download the sequence in requested format
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { writeFileSync } from 'node:fs';
+cli({
+    site: 'gene',
+    name: 'fetch',
+    description: 'Download gene sequence (nucleotide or protein) in FASTA format',
+    database: 'gene',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'NCBI Gene ID (e.g. 7157) or gene symbol with --search' },
+        { name: 'type', default: 'nucleotide', choices: ['nucleotide', 'protein'], help: 'Sequence type to download' },
+        { name: 'output', help: 'Output file path (default: stdout)' },
+    ],
+    columns: ['content'],
+    defaultFormat: 'plain',
+    func: async (ctx, args) => {
+        const geneId = String(args.id).trim();
+        const seqType = String(args.type);
+        const outputFile = args.output ? String(args.output) : undefined;
+        if (!/^\d+$/.test(geneId)) {
+            throw new CliError('ARGUMENT', `Invalid Gene ID: "${geneId}"`, 'Use a numeric NCBI Gene ID (e.g. 7157 for TP53). Use "biocli gene search" to find IDs.');
+        }
+        // Step 1: elink to find linked nucleotide or protein records
+        const linkDb = seqType === 'protein' ? 'protein' : 'nuccore';
+        const linkName = seqType === 'protein' ? 'gene_protein_refseq' : 'gene_nuccore_refseqrna';
+        const linkResult = await ctx.fetchJson(buildEutilsUrl('elink.fcgi', {
+            dbfrom: 'gene',
+            db: linkDb,
+            id: geneId,
+            linkname: linkName,
+            retmode: 'json',
+        }));
+        // Parse elink result to get linked IDs
+        const linksets = (linkResult?.linksets ?? []);
+        let linkedIds = [];
+        if (linksets.length > 0) {
+            const linksetdbs = (linksets[0]?.linksetdbs ?? []);
+            if (linksetdbs.length > 0) {
+                const links = (linksetdbs[0]?.links ?? []);
+                linkedIds = links;
+            }
+        }
+        // Fallback: try broader link name
+        if (!linkedIds.length && seqType === 'nucleotide') {
+            const fallbackResult = await ctx.fetchJson(buildEutilsUrl('elink.fcgi', {
+                dbfrom: 'gene',
+                db: 'nuccore',
+                id: geneId,
+                linkname: 'gene_nuccore_refseqgene',
+                retmode: 'json',
+            }));
+            const fb = (fallbackResult?.linksets ?? []);
+            if (fb.length > 0) {
+                const fbdbs = (fb[0]?.linksetdbs ?? []);
+                if (fbdbs.length > 0) {
+                    linkedIds = (fbdbs[0]?.links ?? []);
+                }
+            }
+        }
+        if (!linkedIds.length) {
+            throw new CliError('NOT_FOUND', `No ${seqType} sequences found for Gene ID ${geneId}`, `Try the other type: biocli gene fetch ${geneId} --type ${seqType === 'protein' ? 'nucleotide' : 'protein'}`);
+        }
+        // Step 2: efetch to download FASTA (use first linked ID)
+        const targetId = linkedIds[0];
+        const fastaUrl = buildEutilsUrl('efetch.fcgi', {
+            db: linkDb,
+            id: targetId,
+            rettype: 'fasta',
+            retmode: 'text',
+        });
+        const fasta = await ctx.fetchText(fastaUrl);
+        if (!fasta || !fasta.startsWith('>')) {
+            throw new CliError('PARSE_ERROR', 'Failed to retrieve FASTA sequence', 'The linked record may not have a sequence available');
+        }
+        // Write to file or return for stdout
+        if (outputFile) {
+            writeFileSync(outputFile, fasta, 'utf-8');
+            const lines = fasta.split('\n');
+            const header = lines[0];
+            const seqLength = lines.slice(1).join('').replace(/\s/g, '').length;
+            return [{ content: `Saved ${seqType} sequence to ${outputFile} (${seqLength} bp/aa, ${header})` }];
+        }
+        return [{ content: fasta.trim() }];
+    },
+});

package/dist/clis/gene/info.d.ts

@@ -0,0 +1,7 @@
+/**
+ * gene/info — Get gene details by NCBI Gene ID.
+ *
+ * Uses esummary (JSON mode) to retrieve comprehensive gene metadata
+ * for a single Gene ID.
+ */
+export {};

package/dist/clis/gene/info.js

@@ -0,0 +1,37 @@
+/**
+ * gene/info — Get gene details by NCBI Gene ID.
+ *
+ * Uses esummary (JSON mode) to retrieve comprehensive gene metadata
+ * for a single Gene ID.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { parseGeneSummaries } from '../_shared/xml-helpers.js';
+cli({
+    site: 'gene',
+    name: 'info',
+    description: 'Get gene details by NCBI Gene ID',
+    database: 'gene',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'NCBI Gene ID (e.g. 7157 for TP53)' },
+    ],
+    columns: ['geneId', 'symbol', 'name', 'organism', 'summary', 'chromosome', 'location'],
+    func: async (ctx, args) => {
+        const geneId = String(args.id).trim();
+        if (!/^\d+$/.test(geneId)) {
+            throw new CliError('ARGUMENT', `Invalid Gene ID: "${geneId}"`, 'Gene ID must be a numeric identifier (e.g. 7157 for TP53)');
+        }
+        const summaryResult = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+            db: 'gene',
+            id: geneId,
+            retmode: 'json',
+        }));
+        const genes = parseGeneSummaries(summaryResult);
+        if (!genes.length) {
+            throw new CliError('NOT_FOUND', `Gene ID ${geneId} not found`, 'Check that the Gene ID is correct (e.g. 7157 for TP53)');
+        }
+        return genes;
+    },
+});

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

@@ -0,0 +1,7 @@
+/**
+ * gene/search — Search NCBI Gene database.
+ *
+ * Uses esearch to find Gene IDs matching the query, then esummary
+ * (JSON mode) to retrieve gene metadata.
+ */
+export {};

package/dist/clis/gene/search.js

@@ -0,0 +1,71 @@
+/**
+ * gene/search — Search NCBI Gene database.
+ *
+ * Uses esearch to find Gene IDs matching the query, then esummary
+ * (JSON mode) to retrieve gene metadata.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { parseGeneSummaries } from '../_shared/xml-helpers.js';
+import { clamp } from '../_shared/common.js';
+import { withMeta } from '../../types.js';
+/** Map common organism names to NCBI search terms. */
+const ORGANISM_MAP = {
+    human: 'Homo sapiens',
+    mouse: 'Mus musculus',
+    rat: 'Rattus norvegicus',
+    zebrafish: 'Danio rerio',
+    fly: 'Drosophila melanogaster',
+    worm: 'Caenorhabditis elegans',
+    yeast: 'Saccharomyces cerevisiae',
+    chicken: 'Gallus gallus',
+    dog: 'Canis lupus familiaris',
+    pig: 'Sus scrofa',
+};
+cli({
+    site: 'gene',
+    name: 'search',
+    description: 'Search NCBI Gene database',
+    database: 'gene',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Gene symbol or keyword (e.g. TP53, BRCA1)' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max results (1-200)' },
+        { name: 'organism', default: 'human', help: 'Organism name (e.g. human, mouse, rat, zebrafish)' },
+    ],
+    columns: ['geneId', 'symbol', 'name', 'organism'],
+    func: async (ctx, args) => {
+        const limit = clamp(Number(args.limit), 1, 200);
+        const orgInput = String(args.organism).toLowerCase().trim();
+        const organism = ORGANISM_MAP[orgInput] ?? String(args.organism);
+        // Build search term: "query[Gene Name] AND organism[Organism]"
+        const query = String(args.query).trim();
+        const term = `${query}[Gene Name] AND ${organism}[Organism]`;
+        // Step 1: esearch to get Gene IDs
+        const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+            db: 'gene',
+            term,
+            retmax: String(limit),
+            retmode: 'json',
+        }));
+        const result = searchResult;
+        const esearchResult = result?.esearchresult;
+        const geneIds = esearchResult?.idlist ?? [];
+        const totalCount = Number(esearchResult?.count ?? 0);
+        if (!geneIds.length) {
+            throw new CliError('NOT_FOUND', `No genes found for "${query}" in ${organism}`, 'Try a different gene name/symbol or organism');
+        }
+        // Step 2: esummary to get gene details (JSON mode works for gene db)
+        const summaryResult = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+            db: 'gene',
+            id: geneIds.join(','),
+            retmode: 'json',
+        }));
+        const genes = parseGeneSummaries(summaryResult);
+        if (!genes.length) {
+            throw new CliError('PARSE_ERROR', 'Failed to parse gene summary data', 'Try again later');
+        }
+        return withMeta(genes, { totalCount, query });
+    },
+});

package/dist/clis/geo/dataset.d.ts

@@ -0,0 +1,7 @@
+/**
+ * geo/dataset — Get GEO dataset details by accession.
+ *
+ * Searches by accession (GSE, GDS, GPL, GSM) in the gds database,
+ * then retrieves the full summary via esummary (JSON).
+ */
+export {};