@yangfei_93sky/biocli 0.2.0 → 0.3.0

package/README.md

@@ -5,13 +5,13 @@ Query biological databases from the terminal. Agent-first design.
 ```
 biocli v0.2.0
 NCBI · UniProt · KEGG · STRING · Ensembl · Enrichr
-42 commands · 6 database backends · 8 workflow commands · 4 download commands
+44 commands · 6 database backends · 10 workflow commands · 4 download commands
 ```
 
 ## Install
 
 ```bash
-npm install -g @biocli/cli
+npm install -g @yangfei_93sky/biocli
 ```
 
 Requires Node.js >= 20. No API keys needed (optional NCBI key increases rate limit).
@@ -75,7 +75,7 @@ Designed for **AI agents** (Claude Code, Codex CLI, etc.) — structured JSON ou
 
 </details>
 
-> All three tools were installed (`npm install -g @biocli/cli`, `pip install gget==0.30.3`, `uv tool install biomcp-cli==0.8.19`) and executed on the same machine with the same inputs. Raw stdout/stderr, scoring scripts, and runner scripts are in [`benchmarks/`](benchmarks/). BioMCP excels at biomedical entity breadth (drugs, trials, diseases) not covered by this task set; gget excels at sequence analysis (BLAST, AlphaFold) not covered here.
+> All three tools were installed (`npm install -g @yangfei_93sky/biocli`, `pip install gget==0.30.3`, `uv tool install biomcp-cli==0.8.19`) and executed on the same machine with the same inputs. Raw stdout/stderr, scoring scripts, and runner scripts are in [`benchmarks/`](benchmarks/). BioMCP excels at biomedical entity breadth (drugs, trials, diseases) not covered by this task set; gget excels at sequence analysis (BLAST, AlphaFold) not covered here.
 
 ## Quick start
 
@@ -118,6 +118,8 @@ biocli aggregate gene-profile TP53
 | `aggregate gene-profile <gene>` | NCBI+UniProt+KEGG+STRING | Gene profile (no literature) |
 | `aggregate workflow-scout <query>` | GEO+SRA | Scout datasets for a research question |
 | `aggregate workflow-prepare <dataset>` | GEO+NCBI+UniProt+KEGG | Prepare research-ready directory with data + annotations |
+| `aggregate workflow-annotate <genes>` | NCBI+UniProt+KEGG+Enrichr | Annotate gene list → genes.csv + pathways.csv + enrichment.csv + report.md |
+| `aggregate workflow-profile <genes>` | NCBI+UniProt+KEGG+STRING+Enrichr | Gene set functional profile → shared pathways, interactions, GO terms |
 
 ### Database commands (atomic)
 

package/dist/cli-manifest.json

@@ -224,6 +224,57 @@
     "type": "ts",
     "modulePath": "aggregate/variant-interpret.js"
   },
+  {
+    "site": "aggregate",
+    "name": "workflow-annotate",
+    "description": "Annotate a gene list into a research-ready directory",
+    "database": "aggregate",
+    "strategy": "public",
+    "args": [
+      {
+        "name": "genes",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Gene symbols: comma-separated (TP53,BRCA1) or use --input file"
+      },
+      {
+        "name": "outdir",
+        "type": "str",
+        "required": true,
+        "help": "Output directory for annotation results"
+      },
+      {
+        "name": "organism",
+        "type": "str",
+        "default": "human",
+        "required": false,
+        "help": "Organism (human, mouse, rat, etc.)"
+      },
+      {
+        "name": "library",
+        "type": "str",
+        "default": "KEGG_2021_Human",
+        "required": false,
+        "help": "Enrichr library for enrichment analysis"
+      },
+      {
+        "name": "plan",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "Preview steps without executing"
+      }
+    ],
+    "columns": [
+      "step",
+      "status",
+      "detail"
+    ],
+    "timeout": 120,
+    "type": "ts",
+    "modulePath": "aggregate/workflow-annotate.js"
+  },
   {
     "site": "aggregate",
     "name": "workflow-prepare",
@@ -267,6 +318,57 @@
     "type": "ts",
     "modulePath": "aggregate/workflow-prepare.js"
   },
+  {
+    "site": "aggregate",
+    "name": "workflow-profile",
+    "description": "Functional profile for a gene set (interactions, GO terms, shared pathways)",
+    "database": "aggregate",
+    "strategy": "public",
+    "args": [
+      {
+        "name": "genes",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Gene symbols: comma-separated (TP53,BRCA1,EGFR,MYC,CDK2)"
+      },
+      {
+        "name": "outdir",
+        "type": "str",
+        "required": true,
+        "help": "Output directory"
+      },
+      {
+        "name": "organism",
+        "type": "str",
+        "default": "human",
+        "required": false,
+        "help": "Organism (human, mouse, rat, etc.)"
+      },
+      {
+        "name": "library",
+        "type": "str",
+        "default": "KEGG_2021_Human",
+        "required": false,
+        "help": "Enrichr library"
+      },
+      {
+        "name": "plan",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "Preview steps without executing"
+      }
+    ],
+    "columns": [
+      "step",
+      "status",
+      "detail"
+    ],
+    "timeout": 180,
+    "type": "ts",
+    "modulePath": "aggregate/workflow-profile.js"
+  },
   {
     "site": "aggregate",
     "name": "workflow-scout",

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

@@ -0,0 +1,15 @@
+/**
+ * aggregate/workflow-annotate — Annotate a gene list into a research-ready directory.
+ *
+ * Input: gene list (comma-separated, --input file, or stdin)
+ * Output directory:
+ *   summary.json    — high-level overview (gene count, sources, warnings)
+ *   genes.csv       — per-gene annotations (symbol, name, function, chromosome, etc.)
+ *   pathways.csv    — all KEGG pathways linked to any input gene
+ *   enrichment.csv  — Enrichr pathway enrichment results
+ *   report.md       — human-readable Markdown report
+ *   manifest.json   — full provenance (biocli version, run timestamp, sources, inputs)
+ *
+ * Cross-queries: NCBI Gene + UniProt + KEGG + Enrichr
+ */
+export {};

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

@@ -0,0 +1,323 @@
+/**
+ * aggregate/workflow-annotate — Annotate a gene list into a research-ready directory.
+ *
+ * Input: gene list (comma-separated, --input file, or stdin)
+ * Output directory:
+ *   summary.json    — high-level overview (gene count, sources, warnings)
+ *   genes.csv       — per-gene annotations (symbol, name, function, chromosome, etc.)
+ *   pathways.csv    — all KEGG pathways linked to any input gene
+ *   enrichment.csv  — Enrichr pathway enrichment results
+ *   report.md       — human-readable Markdown report
+ *   manifest.json   — full provenance (biocli version, run timestamp, sources, inputs)
+ *
+ * Cross-queries: NCBI Gene + UniProt + KEGG + Enrichr
+ */
+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 { submitGeneList, getEnrichment } from '../../databases/enrichr.js';
+import { parseGeneSummaries } from '../_shared/xml-helpers.js';
+import { resolveOrganism } from '../_shared/organism-db.js';
+import { mkdirSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getVersion } from '../../version.js';
+// ── CSV helper ───────────────────────────────────────────────────────────────
+function toCsv(headers, rows) {
+    const escape = (v) => {
+        const s = String(v ?? '');
+        return s.includes(',') || s.includes('"') || s.includes('\n')
+            ? `"${s.replace(/"/g, '""')}"` : s;
+    };
+    const lines = [headers.join(',')];
+    for (const row of rows) {
+        lines.push(headers.map(h => escape(row[h])).join(','));
+    }
+    return lines.join('\n') + '\n';
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+cli({
+    site: 'aggregate',
+    name: 'workflow-annotate',
+    description: 'Annotate a gene list into a research-ready directory',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 120,
+    args: [
+        { name: 'genes', positional: true, required: true, help: 'Gene symbols: comma-separated (TP53,BRCA1) or use --input file' },
+        { name: 'outdir', required: true, help: 'Output directory for annotation results' },
+        { name: 'organism', default: 'human', help: 'Organism (human, mouse, rat, etc.)' },
+        { name: 'library', default: 'KEGG_2021_Human', help: 'Enrichr library for enrichment analysis' },
+        { name: 'plan', type: 'boolean', default: false, help: 'Preview steps without executing' },
+    ],
+    columns: ['step', 'status', 'detail'],
+    func: async (_ctx, args) => {
+        const geneInput = String(args.genes);
+        const genes = geneInput.split(',').map(s => s.trim()).filter(Boolean);
+        const outdir = String(args.outdir);
+        const orgInput = String(args.organism);
+        const library = String(args.library);
+        const planOnly = Boolean(args.plan);
+        if (genes.length === 0) {
+            throw new CliError('ARGUMENT', 'At least one gene symbol is required', 'Example: biocli aggregate workflow-annotate TP53,BRCA1,EGFR --outdir ./results');
+        }
+        const org = resolveOrganism(orgInput);
+        const sources = [];
+        const warnings = [];
+        const steps = [];
+        // ── Plan mode ───────────────────────────────────────────────────────
+        if (planOnly) {
+            return wrapResult({
+                plan: [
+                    { step: 'gene-annotations', detail: `Query NCBI Gene + UniProt for ${genes.length} gene(s)` },
+                    { step: 'pathways', detail: `Query KEGG pathways for each gene` },
+                    { step: 'enrichment', detail: `Run Enrichr enrichment (${library}) for gene set` },
+                    { step: 'output', detail: `Write genes.csv, pathways.csv, enrichment.csv, report.md, summary.json, manifest.json → ${outdir}` },
+                ],
+                genes,
+                organism: org.name,
+                outdir,
+            }, { ids: {}, sources: [], warnings: [], query: genes.join(','), organism: org.name });
+        }
+        // Create output directory
+        if (!existsSync(outdir))
+            mkdirSync(outdir, { recursive: true });
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        const uniprotCtx = createHttpContextForDatabase('uniprot');
+        const keggCtx = createHttpContextForDatabase('kegg');
+        // ── Step 1: Gene annotations (NCBI + UniProt) ───────────────────────
+        const geneAnnotations = [];
+        for (const gene of genes) {
+            const annot = {
+                symbol: gene, ncbiGeneId: '', name: '', summary: '',
+                chromosome: '', location: '', uniprotAccession: '',
+                proteinFunction: '', subcellularLocation: '', goTerms: '',
+            };
+            // NCBI Gene
+            try {
+                const searchResult = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                    db: 'gene', term: `${gene}[Gene Name] AND ${org.name}[Organism]`,
+                    retmax: '5', retmode: 'json',
+                }));
+                const ids = searchResult?.esearchresult?.idlist ?? [];
+                if (ids.length > 0) {
+                    const summaryResult = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+                        db: 'gene', id: ids.join(','), retmode: 'json',
+                    }));
+                    const parsed = parseGeneSummaries(summaryResult);
+                    const best = parsed.find(g => g.symbol.toUpperCase() === gene.toUpperCase()) ?? parsed[0];
+                    if (best) {
+                        annot.ncbiGeneId = best.geneId;
+                        annot.name = best.name;
+                        annot.summary = best.summary;
+                        annot.chromosome = best.chromosome;
+                        annot.location = best.location;
+                    }
+                }
+            }
+            catch (err) {
+                warnings.push(`NCBI Gene ${gene}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // UniProt
+            try {
+                const upResult = await uniprotCtx.fetchJson(buildUniprotUrl('/uniprotkb/search', {
+                    query: `gene:${gene} AND organism_id:${org.taxId} AND reviewed:true`,
+                    format: 'json', size: '5',
+                }));
+                const results = (upResult?.results ?? []);
+                if (results.length > 0) {
+                    const getGeneName = (e) => {
+                        const gs = e.genes;
+                        const gn = gs?.[0];
+                        return String(gn?.geneName?.value ?? '');
+                    };
+                    const exact = results.find(e => getGeneName(e).toUpperCase() === gene.toUpperCase());
+                    const entry = exact ?? results[0];
+                    annot.uniprotAccession = String(entry.primaryAccession ?? '');
+                    const comments = (entry.comments ?? []);
+                    const funcComment = comments.find(c => c.commentType === 'FUNCTION');
+                    const funcTexts = (funcComment?.texts ?? []);
+                    annot.proteinFunction = funcTexts.map(t => String(t.value ?? '')).join(' ');
+                    const locComment = comments.find(c => c.commentType === 'SUBCELLULAR LOCATION');
+                    const locEntries = (locComment?.subcellularLocations ?? []);
+                    annot.subcellularLocation = locEntries.map(l => String(l.location?.value ?? '')).filter(Boolean).join(', ');
+                    const xrefs = (entry.uniProtKBCrossReferences ?? []);
+                    const goTerms = xrefs.filter(x => x.database === 'GO').map(x => {
+                        const props = (x.properties ?? []);
+                        const termProp = props.find(p => p.key === 'GoTerm');
+                        return String(termProp?.value ?? '');
+                    });
+                    annot.goTerms = goTerms.slice(0, 10).join('; ');
+                }
+            }
+            catch (err) {
+                warnings.push(`UniProt ${gene}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            geneAnnotations.push(annot);
+        }
+        if (geneAnnotations.some(a => a.ncbiGeneId))
+            sources.push('NCBI Gene');
+        if (geneAnnotations.some(a => a.uniprotAccession))
+            sources.push('UniProt');
+        writeFileSync(join(outdir, 'genes.csv'), toCsv(['symbol', 'ncbiGeneId', 'name', 'chromosome', 'location', 'uniprotAccession', 'proteinFunction', 'subcellularLocation', 'goTerms', 'summary'], geneAnnotations));
+        steps.push({ step: 'gene-annotations', status: 'done', detail: `${geneAnnotations.length} gene(s) → genes.csv` });
+        // ── Step 2: KEGG pathways ───────────────────────────────────────────
+        const pathwayLinks = [];
+        const pathIdSet = new Set();
+        for (const annot of geneAnnotations) {
+            if (!annot.ncbiGeneId)
+                continue;
+            try {
+                const linkText = await keggCtx.fetchText(buildKeggUrl(`/link/pathway/${org.keggOrg}:${annot.ncbiGeneId}`));
+                if (linkText && linkText.trim()) {
+                    const links = parseKeggTsv(linkText);
+                    for (const l of links) {
+                        const pid = l.value.replace(/^path:/, '');
+                        pathIdSet.add(pid);
+                        pathwayLinks.push({ gene: annot.symbol, pathwayId: pid, pathwayName: '' });
+                    }
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+        // Resolve pathway names
+        if (pathIdSet.size > 0) {
+            try {
+                const listText = await keggCtx.fetchText(buildKeggUrl(`/list/pathway/${org.keggOrg}`));
+                const allPaths = parseKeggTsv(listText);
+                const nameMap = new Map(allPaths.map(p => [p.key, p.value.replace(/ - .*$/, '')]));
+                for (const link of pathwayLinks) {
+                    link.pathwayName = nameMap.get(link.pathwayId) ?? link.pathwayId;
+                }
+                sources.push('KEGG');
+            }
+            catch (err) {
+                warnings.push(`KEGG pathway names: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        writeFileSync(join(outdir, 'pathways.csv'), toCsv(['gene', 'pathwayId', 'pathwayName'], pathwayLinks));
+        steps.push({ step: 'pathways', status: 'done', detail: `${pathwayLinks.length} pathway links (${pathIdSet.size} unique) → pathways.csv` });
+        // ── Step 3: Enrichment (Enrichr) ────────────────────────────────────
+        const enrichmentRows = [];
+        if (genes.length >= 2) {
+            try {
+                const userListId = await submitGeneList(genes);
+                const results = await getEnrichment(userListId, library);
+                for (let i = 0; i < Math.min(results.length, 30); i++) {
+                    const r = results[i];
+                    enrichmentRows.push({
+                        rank: i + 1,
+                        term: String(r.term),
+                        library,
+                        adjustedPValue: Number(r.adjustedPValue).toExponential(2),
+                        combinedScore: Number(r.combinedScore).toFixed(1),
+                        genes: String(r.genes),
+                    });
+                }
+                sources.push('Enrichr');
+            }
+            catch (err) {
+                warnings.push(`Enrichr: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            warnings.push('Enrichment skipped: at least 2 genes required');
+        }
+        writeFileSync(join(outdir, 'enrichment.csv'), toCsv(['rank', 'term', 'library', 'adjustedPValue', 'combinedScore', 'genes'], enrichmentRows));
+        steps.push({ step: 'enrichment', status: enrichmentRows.length > 0 ? 'done' : 'skipped',
+            detail: enrichmentRows.length > 0 ? `${enrichmentRows.length} terms → enrichment.csv` : 'skipped (need ≥ 2 genes)' });
+        // ── Step 4: report.md ───────────────────────────────────────────────
+        const reportLines = [
+            `# Gene Annotation Report`,
+            ``,
+            `**Generated by biocli** v${getVersion()} on ${new Date().toISOString()}`,
+            ``,
+            `## Input`,
+            ``,
+            `- **Genes**: ${genes.join(', ')}`,
+            `- **Organism**: ${org.name}`,
+            `- **Sources**: ${sources.join(', ') || 'none'}`,
+            warnings.length > 0 ? `- **Warnings**: ${warnings.length}` : '',
+            ``,
+            `## Gene Summary`,
+            ``,
+            `| Symbol | Name | Chromosome | UniProt | Function |`,
+            `|--------|------|------------|---------|----------|`,
+        ];
+        for (const g of geneAnnotations) {
+            const func = g.proteinFunction.length > 80 ? g.proteinFunction.slice(0, 80) + '...' : g.proteinFunction;
+            reportLines.push(`| ${g.symbol} | ${g.name} | ${g.chromosome} | ${g.uniprotAccession} | ${func} |`);
+        }
+        if (pathwayLinks.length > 0) {
+            // Deduplicate pathways
+            const uniquePathways = [...new Map(pathwayLinks.map(p => [p.pathwayId, p])).values()];
+            reportLines.push('', `## KEGG Pathways (${uniquePathways.length} unique)`, '', '| Pathway | Genes |', '|---------|-------|');
+            const pathwayGenes = new Map();
+            for (const link of pathwayLinks) {
+                const list = pathwayGenes.get(link.pathwayName) ?? [];
+                list.push(link.gene);
+                pathwayGenes.set(link.pathwayName, list);
+            }
+            for (const [name, gList] of [...pathwayGenes.entries()].slice(0, 20)) {
+                reportLines.push(`| ${name} | ${[...new Set(gList)].join(', ')} |`);
+            }
+        }
+        if (enrichmentRows.length > 0) {
+            reportLines.push('', `## Enrichment Analysis (${library})`, '', '| Rank | Term | Adj. P-value | Genes |', '|------|------|-------------|-------|');
+            for (const r of enrichmentRows.slice(0, 15)) {
+                reportLines.push(`| ${r.rank} | ${r.term} | ${r.adjustedPValue} | ${r.genes} |`);
+            }
+        }
+        if (warnings.length > 0) {
+            reportLines.push('', '## Warnings', '');
+            for (const w of warnings)
+                reportLines.push(`- ${w}`);
+        }
+        reportLines.push('', '---', `*Report generated by [biocli](https://github.com/youngfly93/biocli)*`);
+        writeFileSync(join(outdir, 'report.md'), reportLines.filter(l => l !== undefined).join('\n') + '\n');
+        steps.push({ step: 'report', status: 'done', detail: `report.md → ${outdir}` });
+        // ── Step 5: summary.json + manifest.json ────────────────────────────
+        const summary = {
+            geneCount: genes.length,
+            annotatedCount: geneAnnotations.filter(a => a.ncbiGeneId).length,
+            pathwayCount: pathIdSet.size,
+            enrichmentTerms: enrichmentRows.length,
+            sources,
+            warnings,
+        };
+        writeFileSync(join(outdir, 'summary.json'), JSON.stringify(summary, null, 2));
+        const manifest = {
+            biocliVersion: getVersion(),
+            createdAt: new Date().toISOString(),
+            command: 'workflow-annotate',
+            input: { genes, organism: org.name, library },
+            output: {
+                'genes.csv': `${geneAnnotations.length} genes`,
+                'pathways.csv': `${pathwayLinks.length} pathway links`,
+                'enrichment.csv': `${enrichmentRows.length} terms`,
+                'report.md': 'Markdown report',
+                'summary.json': 'Overview statistics',
+            },
+            sources,
+            warnings,
+        };
+        steps.push({ step: 'manifest', status: 'done', detail: `summary.json + manifest.json → ${outdir}` });
+        writeFileSync(join(outdir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        return wrapResult({
+            outdir,
+            genes,
+            steps,
+            summary,
+        }, {
+            ids: {},
+            sources,
+            warnings,
+            query: genes.join(','),
+            organism: org.name,
+        });
+    },
+});

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

@@ -0,0 +1,17 @@
+/**
+ * aggregate/workflow-profile — Functional profile for a gene set.
+ *
+ * Unlike workflow-annotate (per-gene annotations), this command focuses on
+ * the SET-LEVEL view: shared pathways, interaction network, GO term
+ * distribution, and enrichment. Think "what does this gene set DO together?"
+ *
+ * Output directory:
+ *   profiles.json       — per-gene profile summaries (from gene-profile)
+ *   interactions.csv    — STRING protein-protein interaction network
+ *   go_summary.csv      — GO term frequency across the gene set
+ *   shared_pathways.csv — KEGG pathways shared by 2+ input genes
+ *   enrichment.csv      — Enrichr enrichment results
+ *   report.md           — human-readable Markdown report
+ *   manifest.json       — provenance
+ */
+export {};

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

@@ -0,0 +1,326 @@
+/**
+ * aggregate/workflow-profile — Functional profile for a gene set.
+ *
+ * Unlike workflow-annotate (per-gene annotations), this command focuses on
+ * the SET-LEVEL view: shared pathways, interaction network, GO term
+ * distribution, and enrichment. Think "what does this gene set DO together?"
+ *
+ * Output directory:
+ *   profiles.json       — per-gene profile summaries (from gene-profile)
+ *   interactions.csv    — STRING protein-protein interaction network
+ *   go_summary.csv      — GO term frequency across the gene set
+ *   shared_pathways.csv — KEGG pathways shared by 2+ input genes
+ *   enrichment.csv      — Enrichr enrichment results
+ *   report.md           — human-readable Markdown report
+ *   manifest.json       — provenance
+ */
+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 { buildStringUrl } from '../../databases/string-db.js';
+import { submitGeneList, getEnrichment } from '../../databases/enrichr.js';
+import { parseGeneSummaries } from '../_shared/xml-helpers.js';
+import { resolveOrganism } from '../_shared/organism-db.js';
+import { mkdirSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getVersion } from '../../version.js';
+// ── CSV helper ───────────────────────────────────────────────────────────────
+function toCsv(headers, rows) {
+    const escape = (v) => {
+        const s = String(v ?? '');
+        return s.includes(',') || s.includes('"') || s.includes('\n')
+            ? `"${s.replace(/"/g, '""')}"` : s;
+    };
+    return [headers.join(','), ...rows.map(r => headers.map(h => escape(r[h])).join(','))].join('\n') + '\n';
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+cli({
+    site: 'aggregate',
+    name: 'workflow-profile',
+    description: 'Functional profile for a gene set (interactions, GO terms, shared pathways)',
+    database: 'aggregate',
+    strategy: Strategy.PUBLIC,
+    defaultFormat: 'json',
+    timeoutSeconds: 180,
+    args: [
+        { name: 'genes', positional: true, required: true, help: 'Gene symbols: comma-separated (TP53,BRCA1,EGFR,MYC,CDK2)' },
+        { name: 'outdir', required: true, help: 'Output directory' },
+        { name: 'organism', default: 'human', help: 'Organism (human, mouse, rat, etc.)' },
+        { name: 'library', default: 'KEGG_2021_Human', help: 'Enrichr library' },
+        { name: 'plan', type: 'boolean', default: false, help: 'Preview steps without executing' },
+    ],
+    columns: ['step', 'status', 'detail'],
+    func: async (_ctx, args) => {
+        const genes = String(args.genes).split(',').map(s => s.trim()).filter(Boolean);
+        const outdir = String(args.outdir);
+        const library = String(args.library);
+        const planOnly = Boolean(args.plan);
+        if (genes.length < 2) {
+            throw new CliError('ARGUMENT', 'At least 2 gene symbols required for profiling', 'Example: biocli aggregate workflow-profile TP53,BRCA1,EGFR,MYC,CDK2 --outdir ./profile');
+        }
+        const org = resolveOrganism(String(args.organism));
+        const sources = [];
+        const warnings = [];
+        const steps = [];
+        if (planOnly) {
+            return wrapResult({
+                plan: [
+                    { step: 'gene-profiles', detail: `Query NCBI Gene + UniProt for ${genes.length} gene(s)` },
+                    { step: 'interactions', detail: `Query STRING network for all ${genes.length} genes` },
+                    { step: 'pathways', detail: `Find KEGG pathways shared by 2+ genes` },
+                    { step: 'go-summary', detail: `Aggregate GO terms across gene set` },
+                    { step: 'enrichment', detail: `Run Enrichr (${library})` },
+                    { step: 'output', detail: `Write profiles.json, interactions.csv, go_summary.csv, shared_pathways.csv, enrichment.csv, report.md → ${outdir}` },
+                ],
+                genes, organism: org.name, outdir,
+            }, { ids: {}, sources: [], warnings: [], query: genes.join(','), organism: org.name });
+        }
+        if (!existsSync(outdir))
+            mkdirSync(outdir, { recursive: true });
+        const ncbiCtx = createHttpContextForDatabase('ncbi');
+        const uniprotCtx = createHttpContextForDatabase('uniprot');
+        const keggCtx = createHttpContextForDatabase('kegg');
+        const stringCtx = createHttpContextForDatabase('string');
+        // ── Step 1: Per-gene profiles (NCBI + UniProt) ──────────────────────
+        const profiles = [];
+        const geneIds = {}; // symbol → ncbi gene id
+        const allGoTerms = [];
+        for (const gene of genes) {
+            const profile = { symbol: gene };
+            try {
+                const sr = await ncbiCtx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+                    db: 'gene', term: `${gene}[Gene Name] AND ${org.name}[Organism]`,
+                    retmax: '5', retmode: 'json',
+                }));
+                const ids = sr?.esearchresult?.idlist ?? [];
+                if (ids.length > 0) {
+                    const summ = await ncbiCtx.fetchJson(buildEutilsUrl('esummary.fcgi', { db: 'gene', id: ids.join(','), retmode: 'json' }));
+                    const parsed = parseGeneSummaries(summ);
+                    const best = parsed.find(g => g.symbol.toUpperCase() === gene.toUpperCase()) ?? parsed[0];
+                    if (best) {
+                        profile.ncbiGeneId = best.geneId;
+                        profile.name = best.name;
+                        profile.chromosome = best.chromosome;
+                        geneIds[gene] = best.geneId;
+                    }
+                }
+            }
+            catch (err) {
+                warnings.push(`NCBI ${gene}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                const upResult = await uniprotCtx.fetchJson(buildUniprotUrl('/uniprotkb/search', {
+                    query: `gene:${gene} AND organism_id:${org.taxId} AND reviewed:true`, format: 'json', size: '5',
+                }));
+                const results = (upResult?.results ?? []);
+                if (results.length > 0) {
+                    const getGN = (e) => String(e.genes?.[0]?.geneName?.value ?? '');
+                    const entry = results.find(e => getGN(e).toUpperCase() === gene.toUpperCase()) ?? results[0];
+                    profile.uniprotAccession = entry.primaryAccession;
+                    const comments = (entry.comments ?? []);
+                    const funcComment = comments.find(c => c.commentType === 'FUNCTION');
+                    const funcTexts = (funcComment?.texts ?? []);
+                    profile.function = funcTexts.map(t => String(t.value ?? '')).join(' ');
+                    const xrefs = (entry.uniProtKBCrossReferences ?? []);
+                    xrefs.filter(x => x.database === 'GO').forEach(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(':');
+                        allGoTerms.push({ gene, id, name: nameParts.join(':'), aspect: aspectMap[aspect] ?? aspect });
+                    });
+                }
+            }
+            catch (err) {
+                warnings.push(`UniProt ${gene}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            profiles.push(profile);
+        }
+        if (profiles.some(p => p.ncbiGeneId))
+            sources.push('NCBI Gene');
+        if (profiles.some(p => p.uniprotAccession))
+            sources.push('UniProt');
+        writeFileSync(join(outdir, 'profiles.json'), JSON.stringify(profiles, null, 2));
+        steps.push({ step: 'gene-profiles', status: 'done', detail: `${profiles.length} gene(s) → profiles.json` });
+        // ── Step 2: STRING interactions ──────────────────────────────────────
+        const interactions = [];
+        try {
+            const data = await stringCtx.fetchJson(buildStringUrl('network', {
+                identifiers: genes.join('%0d'),
+                species: String(org.taxId),
+                required_score: '400',
+            }));
+            if (Array.isArray(data)) {
+                for (const item of data) {
+                    interactions.push({
+                        geneA: String(item.preferredName_A ?? ''),
+                        geneB: String(item.preferredName_B ?? ''),
+                        score: Number(item.score ?? 0),
+                        experimentalScore: Number(item.escore ?? 0),
+                        databaseScore: Number(item.dscore ?? 0),
+                        textminingScore: Number(item.tscore ?? 0),
+                    });
+                }
+                sources.push('STRING');
+            }
+        }
+        catch (err) {
+            warnings.push(`STRING: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        writeFileSync(join(outdir, 'interactions.csv'), toCsv(['geneA', 'geneB', 'score', 'experimentalScore', 'databaseScore', 'textminingScore'], interactions));
+        steps.push({ step: 'interactions', status: 'done', detail: `${interactions.length} interactions → interactions.csv` });
+        // ── Step 3: Shared KEGG pathways ────────────────────────────────────
+        const genePathways = {};
+        const pathwayGenes = {};
+        for (const gene of genes) {
+            const gid = geneIds[gene];
+            if (!gid)
+                continue;
+            try {
+                const linkText = await keggCtx.fetchText(buildKeggUrl(`/link/pathway/${org.keggOrg}:${gid}`));
+                if (linkText?.trim()) {
+                    const links = parseKeggTsv(linkText);
+                    genePathways[gene] = new Set(links.map(l => l.value.replace(/^path:/, '')));
+                    for (const pid of genePathways[gene]) {
+                        if (!pathwayGenes[pid])
+                            pathwayGenes[pid] = new Set();
+                        pathwayGenes[pid].add(gene);
+                    }
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+        // Resolve pathway names
+        let pathNameMap = new Map();
+        try {
+            const listText = await keggCtx.fetchText(buildKeggUrl(`/list/pathway/${org.keggOrg}`));
+            pathNameMap = new Map(parseKeggTsv(listText).map(p => [p.key, p.value.replace(/ - .*$/, '')]));
+            if (Object.keys(pathwayGenes).length > 0)
+                sources.push('KEGG');
+        }
+        catch { /* non-fatal */ }
+        // Only pathways shared by 2+ genes
+        const sharedPathways = Object.entries(pathwayGenes)
+            .filter(([, gSet]) => gSet.size >= 2)
+            .map(([pid, gSet]) => ({
+            pathwayId: pid,
+            pathwayName: pathNameMap.get(pid) ?? pid,
+            geneCount: gSet.size,
+            genes: [...gSet].join(', '),
+        }))
+            .sort((a, b) => b.geneCount - a.geneCount);
+        writeFileSync(join(outdir, 'shared_pathways.csv'), toCsv(['pathwayId', 'pathwayName', 'geneCount', 'genes'], sharedPathways));
+        steps.push({ step: 'shared-pathways', status: 'done', detail: `${sharedPathways.length} pathways shared by 2+ genes → shared_pathways.csv` });
+        // ── Step 4: GO term frequency ───────────────────────────────────────
+        const goFreq = {};
+        for (const gt of allGoTerms) {
+            if (!goFreq[gt.id])
+                goFreq[gt.id] = { id: gt.id, name: gt.name, aspect: gt.aspect, genes: new Set() };
+            goFreq[gt.id].genes.add(gt.gene);
+        }
+        const goSummary = Object.values(goFreq)
+            .map(g => ({ id: g.id, name: g.name, aspect: g.aspect, geneCount: g.genes.size, genes: [...g.genes].join(', ') }))
+            .sort((a, b) => b.geneCount - a.geneCount);
+        writeFileSync(join(outdir, 'go_summary.csv'), toCsv(['id', 'name', 'aspect', 'geneCount', 'genes'], goSummary));
+        steps.push({ step: 'go-summary', status: 'done', detail: `${goSummary.length} GO terms → go_summary.csv` });
+        // ── Step 5: Enrichment ──────────────────────────────────────────────
+        const enrichmentRows = [];
+        try {
+            const userListId = await submitGeneList(genes);
+            const results = await getEnrichment(userListId, library);
+            for (let i = 0; i < Math.min(results.length, 30); i++) {
+                const r = results[i];
+                enrichmentRows.push({
+                    rank: i + 1, term: r.term, library,
+                    adjustedPValue: Number(r.adjustedPValue).toExponential(2),
+                    combinedScore: Number(r.combinedScore).toFixed(1),
+                    genes: r.genes,
+                });
+            }
+            sources.push('Enrichr');
+        }
+        catch (err) {
+            warnings.push(`Enrichr: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        writeFileSync(join(outdir, 'enrichment.csv'), toCsv(['rank', 'term', 'library', 'adjustedPValue', 'combinedScore', 'genes'], enrichmentRows));
+        steps.push({ step: 'enrichment', status: enrichmentRows.length > 0 ? 'done' : 'skipped',
+            detail: `${enrichmentRows.length} terms → enrichment.csv` });
+        // ── Step 6: report.md ───────────────────────────────────────────────
+        const lines = [
+            `# Gene Set Functional Profile`, '',
+            `**Generated by biocli** v${getVersion()} on ${new Date().toISOString()}`, '',
+            `## Input`, '',
+            `- **Genes**: ${genes.join(', ')} (${genes.length})`,
+            `- **Organism**: ${org.name}`,
+            `- **Sources**: ${sources.join(', ')}`,
+            warnings.length > 0 ? `- **Warnings**: ${warnings.length}` : '', '',
+        ];
+        if (sharedPathways.length > 0) {
+            lines.push(`## Shared Pathways (${sharedPathways.length})`, '', '| Pathway | Genes | Count |', '|---------|-------|-------|');
+            for (const p of sharedPathways.slice(0, 20)) {
+                lines.push(`| ${p.pathwayName} | ${p.genes} | ${p.geneCount} |`);
+            }
+            lines.push('');
+        }
+        if (interactions.length > 0) {
+            lines.push(`## Protein Interactions (${interactions.length})`, '', '| Gene A | Gene B | Score |', '|--------|--------|-------|');
+            for (const i of interactions.slice(0, 20)) {
+                lines.push(`| ${i.geneA} | ${i.geneB} | ${i.score} |`);
+            }
+            lines.push('');
+        }
+        if (goSummary.length > 0) {
+            const topGo = goSummary.filter(g => g.geneCount >= 2).slice(0, 15);
+            if (topGo.length > 0) {
+                lines.push(`## GO Terms Shared by 2+ Genes (${topGo.length})`, '', '| GO Term | Aspect | Genes | Count |', '|---------|--------|-------|-------|');
+                for (const g of topGo) {
+                    lines.push(`| ${g.name} | ${g.aspect} | ${g.genes} | ${g.geneCount} |`);
+                }
+                lines.push('');
+            }
+        }
+        if (enrichmentRows.length > 0) {
+            lines.push(`## Enrichment (${library})`, '', '| Rank | Term | Adj. P-value | Genes |', '|------|------|-------------|-------|');
+            for (const r of enrichmentRows.slice(0, 15)) {
+                lines.push(`| ${r.rank} | ${r.term} | ${r.adjustedPValue} | ${r.genes} |`);
+            }
+            lines.push('');
+        }
+        if (warnings.length > 0) {
+            lines.push('## Warnings', '');
+            for (const w of warnings)
+                lines.push(`- ${w}`);
+            lines.push('');
+        }
+        lines.push('---', `*Generated by [biocli](https://github.com/youngfly93/biocli)*`);
+        writeFileSync(join(outdir, 'report.md'), lines.filter(l => l !== undefined).join('\n') + '\n');
+        steps.push({ step: 'report', status: 'done', detail: `report.md → ${outdir}` });
+        // ── manifest.json ───────────────────────────────────────────────────
+        const manifest = {
+            biocliVersion: getVersion(), createdAt: new Date().toISOString(),
+            command: 'workflow-profile', input: { genes, organism: org.name, library },
+            output: {
+                'profiles.json': `${profiles.length} gene profiles`,
+                'interactions.csv': `${interactions.length} interactions`,
+                'shared_pathways.csv': `${sharedPathways.length} shared pathways`,
+                'go_summary.csv': `${goSummary.length} GO terms`,
+                'enrichment.csv': `${enrichmentRows.length} enrichment terms`,
+                'report.md': 'Markdown report',
+            },
+            sources, warnings,
+        };
+        steps.push({ step: 'manifest', status: 'done', detail: `manifest.json → ${outdir}` });
+        writeFileSync(join(outdir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        return wrapResult({ outdir, genes, steps, summary: {
+                geneCount: genes.length, interactionCount: interactions.length,
+                sharedPathwayCount: sharedPathways.length, goTermCount: goSummary.length,
+                enrichmentTerms: enrichmentRows.length, sources, warnings,
+            } }, { ids: {}, sources, warnings, query: genes.join(','), organism: org.name });
+    },
+});

package/dist/clis/geo/download.js

@@ -10,7 +10,7 @@
  */
 import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
-import { mkdirSync, existsSync, createWriteStream } from 'node:fs';
+import { mkdirSync, existsSync, createWriteStream, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
@@ -96,6 +96,24 @@ cli({
         for (const file of files) {
             const fileUrl = `${supplUrl}${file.name}`;
             const destPath = join(outdir, file.name);
+            // Resume: skip only if local file matches expected remote size
+            if (existsSync(destPath) && statSync(destPath).size > 0) {
+                try {
+                    const head = await fetch(fileUrl, { method: 'HEAD' });
+                    if (head.ok) {
+                        const expectedSize = Number(head.headers.get('content-length') ?? 0);
+                        const localSize = statSync(destPath).size;
+                        if (expectedSize > 0 && localSize === expectedSize) {
+                            rows.push({ file: file.name, size: file.size, status: `skipped (complete)` });
+                            continue;
+                        }
+                        // Incomplete or mismatched — will re-download below
+                    }
+                }
+                catch {
+                    // HEAD failed — proceed with download
+                }
+            }
             try {
                 const response = await fetch(fileUrl);
                 if (!response.ok || !response.body) {

package/dist/clis/sra/download.js

@@ -13,7 +13,7 @@
  */
 import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
-import { mkdirSync, existsSync, createWriteStream } from 'node:fs';
+import { mkdirSync, existsSync, createWriteStream, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
@@ -141,6 +141,29 @@ cli({
                     catch { /* skip */ }
                     continue;
                 }
+                // Resume: skip if file already exists AND matches expected size (HEAD check)
+                if (existsSync(destPath) && statSync(destPath).size > 0) {
+                    try {
+                        const head = await fetch(url, { method: 'HEAD' });
+                        if (head.ok) {
+                            const expectedSize = Number(head.headers.get('content-length') ?? 0);
+                            const localSize = statSync(destPath).size;
+                            if (expectedSize > 0 && localSize === expectedSize) {
+                                rows.push({ file: fileName, size: formatSize(localSize), status: `skipped (complete, ${formatSize(localSize)})` });
+                                continue;
+                            }
+                            else if (expectedSize > 0 && localSize < expectedSize) {
+                                // Incomplete file — delete and re-download
+                                const { rmSync } = await import('node:fs');
+                                rmSync(destPath);
+                            }
+                            // localSize > expectedSize or expectedSize unknown: re-download
+                        }
+                    }
+                    catch {
+                        // HEAD failed — proceed with download
+                    }
+                }
                 try {
                     // Max-size check: HEAD request first to get size
                     if (maxSizeBytes < Infinity) {

package/dist/commander-adapter.js

@@ -68,7 +68,8 @@ export function registerCommandToProgram(siteCmd, cmd) {
         .option('-A, --all-columns', 'Show all available columns', false)
         .option('-v, --verbose', 'Debug output', false)
         .option('--input <file>', 'Batch input: file with one ID per line, or - for stdin')
-        .option('--no-cache', 'Skip cache and fetch fresh data');
+        .option('--no-cache', 'Skip cache and fetch fresh data')
+        .option('--retry <n>', 'Retry failed batch items N times (default: 0)', '0');
     subCmd.action(async (...actionArgs) => {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
         const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
@@ -92,6 +93,18 @@ export function registerCommandToProgram(siteCmd, cmd) {
             }
             const verbose = optionsRecord.verbose === true;
             const inputFile = typeof optionsRecord.input === 'string' ? optionsRecord.input : undefined;
+            // If --input is provided, read file and inject into positional arg.
+            // Only for commands whose positional arg is named "genes" (multi-entity pattern).
+            // Single-entity commands (gene-dossier, variant-dossier, etc.) use batch mode instead.
+            const primaryArgName = positionalArgs[0]?.name;
+            const supportsInputInject = primaryArgName === 'genes';
+            if (inputFile && supportsInputInject && !kwargs[primaryArgName]) {
+                const { parseBatchInput: parseInput } = await import('./batch.js');
+                const items = parseInput(undefined, inputFile);
+                if (items && items.length > 0) {
+                    kwargs[primaryArgName] = items.join(',');
+                }
+            }
             // Validate required positional args (unless --input provides batch input)
             if (!inputFile) {
                 for (const arg of positionalArgs) {
@@ -113,17 +126,21 @@ export function registerCommandToProgram(siteCmd, cmd) {
             // Commander's --no-cache sets optionsRecord.cache to false
             const noCache = optionsRecord.cache === false;
             // ── Batch mode: --input or comma-separated positional ────────────
+            // Skip batch for aggregate commands — they handle their own multi-input parsing
             const primaryArg = positionalArgs[0]; // first positional = primary ID/query
-            const batchItems = primaryArg
+            const skipBatch = cmd.database === 'aggregate';
+            const batchItems = (primaryArg && !skipBatch)
                 ? parseBatchInput(kwargs[primaryArg.name], inputFile)
                 : null;
+            const retryCount = Math.max(0, parseInt(String(optionsRecord.retry ?? '0'), 10) || 0);
             let result;
             if (batchItems && primaryArg) {
                 const spinnerLabel = `Batch ${fullName(cmd)} (${batchItems.length} items)…`;
                 const spinner = startSpinner(spinnerLabel);
                 const batchResults = [];
-                const errors = [];
+                let failedItems = [];
                 try {
+                    // First pass
                     for (const item of batchItems) {
                         try {
                             const batchKwargs = { ...kwargs, [primaryArg.name]: item };
@@ -132,19 +149,35 @@ export function registerCommandToProgram(siteCmd, cmd) {
                                 batchResults.push(r);
                         }
                         catch (err) {
-                            errors.push(`${item}: ${err instanceof Error ? err.message : String(err)}`);
+                            failedItems.push(item);
                             if (verbose)
                                 console.error(chalk.yellow(`[Batch] ${item} failed: ${err instanceof Error ? err.message : String(err)}`));
                         }
                     }
+                    // Retry failed items
+                    for (let attempt = 1; attempt <= retryCount && failedItems.length > 0; attempt++) {
+                        if (verbose)
+                            console.error(chalk.dim(`[Batch] Retry ${attempt}/${retryCount}: ${failedItems.length} item(s)…`));
+                        const stillFailed = [];
+                        for (const item of failedItems) {
+                            try {
+                                const batchKwargs = { ...kwargs, [primaryArg.name]: item };
+                                const r = await executeCommand(cmd, batchKwargs, verbose, { noCache: true });
+                                if (r !== null && r !== undefined)
+                                    batchResults.push(r);
+                            }
+                            catch {
+                                stillFailed.push(item);
+                            }
+                        }
+                        failedItems = stillFailed;
+                    }
                 }
                 finally {
                     spinner.stop();
                 }
-                if (errors.length > 0) {
-                    console.error(chalk.yellow(`[Batch] ${errors.length}/${batchItems.length} failed`));
-                    if (verbose)
-                        errors.forEach(e => console.error(chalk.dim(`  ${e}`)));
+                if (failedItems.length > 0) {
+                    console.error(chalk.yellow(`[Batch] ${failedItems.length}/${batchItems.length} failed${retryCount > 0 ? ` (after ${retryCount} retries)` : ''}: ${failedItems.join(', ')}`));
                 }
                 if (!batchResults.length) {
                     console.error(chalk.red(`All ${batchItems.length} batch items failed.`));
@@ -168,7 +201,8 @@ export function registerCommandToProgram(siteCmd, cmd) {
             if (result === null || result === undefined) {
                 return;
             }
-            // Extract display metadata if the command returned ResultWithMeta
+            // Extract display metadata if the command returned ResultWithMeta or BiocliResult
+            let biocliResultColumns = false;
             let renderData = result;
             let totalCount;
             let query;
@@ -177,6 +211,22 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 totalCount = result.meta.totalCount;
                 query = result.meta.query;
             }
+            else if (typeof result === 'object' && result !== null && 'data' in result && 'sources' in result) {
+                // BiocliResult envelope — for report/table/csv, render the data payload
+                const biocliResult = result;
+                query = String(biocliResult.query ?? '');
+                if (format === 'json' || format === 'yaml' || format === 'yml') {
+                    // JSON/YAML: render the full envelope (agent-friendly)
+                    renderData = result;
+                }
+                else {
+                    // table/csv/report/md: render the data payload with actual keys
+                    renderData = biocliResult.data;
+                    // Override columns to use data's actual keys (command-declared columns
+                    // may not match the BiocliResult data payload field names)
+                    biocliResultColumns = true;
+                }
+            }
             const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
             if (format === 'table' && resolved.defaultFormat) {
                 format = resolved.defaultFormat;
@@ -192,8 +242,9 @@ export function registerCommandToProgram(siteCmd, cmd) {
             //   --columns pmid,title,abstract  →  user-specified subset
             //   --all-columns / -A             →  all keys from first row
             //   (default)                       →  adapter-declared columns
-            let displayColumns = resolved.columns;
-            const allColumns = optionsRecord.allColumns === true;
+            // For BiocliResult data, use actual keys from the data payload
+            let displayColumns = biocliResultColumns ? undefined : resolved.columns;
+            const allColumns = optionsRecord.allColumns === true || biocliResultColumns;
             const userColumns = typeof optionsRecord.columns === 'string' ? optionsRecord.columns : undefined;
             if (userColumns) {
                 displayColumns = userColumns.split(',').map((s) => s.trim()).filter(Boolean);

package/dist/output.js

@@ -194,6 +194,9 @@ export function render(data, opts = {}) {
         case 'markdown':
             renderMarkdown(data, opts);
             break;
+        case 'report':
+            renderReport(data, opts);
+            break;
         case 'csv':
             renderCsv(data, opts);
             break;
@@ -386,6 +389,55 @@ function renderCsv(data, opts) {
         }).join(','));
     }
 }
+function renderReport(data, opts) {
+    const rows = normalizeRows(data);
+    const columns = resolveColumns(rows, opts);
+    // Title
+    const title = opts.title ?? opts.source ?? 'biocli Report';
+    console.log(`# ${title}`);
+    console.log();
+    console.log(`*Generated on ${new Date().toISOString()}*`);
+    console.log();
+    // Metadata
+    if (opts.query)
+        console.log(`**Query**: ${opts.query}`);
+    if (opts.totalCount !== undefined)
+        console.log(`**Total results**: ${opts.totalCount} (showing ${rows.length})`);
+    console.log(`**Columns**: ${columns.join(', ')}`);
+    console.log();
+    if (!rows.length) {
+        console.log('*No results found.*');
+        return;
+    }
+    // Data table
+    console.log('## Results');
+    console.log();
+    console.log('| ' + columns.join(' | ') + ' |');
+    console.log('| ' + columns.map(() => '---').join(' | ') + ' |');
+    for (const row of rows) {
+        const cells = columns.map(c => {
+            const raw = row[c];
+            // Format nested objects/arrays for report readability
+            let v;
+            if (Array.isArray(raw)) {
+                v = `${raw.length} items`;
+            }
+            else if (raw !== null && typeof raw === 'object') {
+                v = JSON.stringify(raw);
+            }
+            else {
+                v = String(raw ?? '');
+            }
+            // Truncate long values and escape pipes for Markdown
+            v = v.replace(/\|/g, '\\|');
+            return v.length > 80 ? v.slice(0, 80) + '...' : v;
+        });
+        console.log('| ' + cells.join(' | ') + ' |');
+    }
+    console.log();
+    console.log('---');
+    console.log('*Generated by [biocli](https://github.com/youngfly93/biocli)*');
+}
 function renderYaml(data) {
     console.log(yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangfei_93sky/biocli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Query biological databases from the terminal — agent-first bioinformatics CLI",
   "type": "module",
   "main": "dist/main.js",