@yangfei_93sky/biocli 0.2.0

package/dist/clis/pubmed/cited-by.js

@@ -0,0 +1,77 @@
+/**
+ * pubmed/cited-by — Find articles that cite a given PubMed article.
+ *
+ * Uses elink with linkname 'pubmed_pubmed_citedin' to discover citing
+ * PMIDs, then efetch to retrieve article metadata.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { parsePubmedArticles } from '../_shared/xml-helpers.js';
+import { clamp } from '../_shared/common.js';
+import { isRecord } from '../../utils.js';
+cli({
+    site: 'pubmed',
+    name: 'cited-by',
+    description: 'Articles that cite a PubMed article',
+    database: 'pubmed',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'pmid', positional: true, required: true, help: 'PubMed ID' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max results (1-100)' },
+    ],
+    columns: ['pmid', 'title', 'authors', 'journal', 'year', 'doi'],
+    func: async (ctx, args) => {
+        const pmid = String(args.pmid).trim();
+        if (!/^\d+$/.test(pmid)) {
+            throw new CliError('ARGUMENT', `Invalid PMID: "${pmid}"`, 'PMID must be a numeric identifier');
+        }
+        const limit = clamp(Number(args.limit), 1, 100);
+        // Step 1: elink to get citing PMIDs
+        const linkResult = await ctx.fetchJson(buildEutilsUrl('elink.fcgi', {
+            dbfrom: 'pubmed',
+            db: 'pubmed',
+            id: pmid,
+            linkname: 'pubmed_pubmed_citedin',
+            retmode: 'json',
+        }));
+        // Navigate elink JSON response:
+        // { linksets: [{ linksetdbs: [{ links: ["12345", ...] }] }] }
+        const linksets = linkResult?.linksets;
+        if (!Array.isArray(linksets) || !linksets.length) {
+            throw new CliError('NOT_FOUND', `No citing articles found for PMID ${pmid}`, 'This article may not have been cited yet');
+        }
+        const firstLinkset = linksets[0];
+        const linksetdbs = firstLinkset?.linksetdbs;
+        if (!Array.isArray(linksetdbs) || !linksetdbs.length) {
+            throw new CliError('NOT_FOUND', `No citing articles found for PMID ${pmid}`, 'This article may not have been cited yet');
+        }
+        // Find the correct linksetdb entry
+        let citingIds = [];
+        for (const lsdb of linksetdbs) {
+            if (!isRecord(lsdb))
+                continue;
+            const links = lsdb.links;
+            if (Array.isArray(links) && links.length > 0) {
+                citingIds = links.map(String);
+                break;
+            }
+        }
+        if (!citingIds.length) {
+            throw new CliError('NOT_FOUND', `No citing articles found for PMID ${pmid}`, 'This article may not have been cited yet');
+        }
+        // Trim to requested limit
+        const trimmedIds = citingIds.slice(0, limit);
+        // Step 2: efetch those PMIDs
+        const xmlData = await ctx.fetchXml(buildEutilsUrl('efetch.fcgi', {
+            db: 'pubmed',
+            id: trimmedIds.join(','),
+            rettype: 'xml',
+        }));
+        const articles = parsePubmedArticles(xmlData);
+        if (!articles.length) {
+            throw new CliError('PARSE_ERROR', 'Failed to parse citing articles', 'Try again later');
+        }
+        return articles;
+    },
+});

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

@@ -0,0 +1,6 @@
+/**
+ * pubmed/fetch — Get PubMed article details by PMID.
+ *
+ * Fetches a single article and returns full metadata including abstract.
+ */
+export {};

package/dist/clis/pubmed/fetch.js

@@ -0,0 +1,36 @@
+/**
+ * pubmed/fetch — Get PubMed article details by PMID.
+ *
+ * Fetches a single article and returns full metadata including abstract.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { parsePubmedArticles } from '../_shared/xml-helpers.js';
+cli({
+    site: 'pubmed',
+    name: 'fetch',
+    description: 'Get PubMed article details by PMID',
+    database: 'pubmed',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'pmid', positional: true, required: true, help: 'PubMed ID (e.g. 39088800)' },
+    ],
+    columns: ['pmid', 'title', 'authors', 'journal', 'year', 'doi', 'abstract'],
+    func: async (ctx, args) => {
+        const pmid = String(args.pmid).trim();
+        if (!/^\d+$/.test(pmid)) {
+            throw new CliError('ARGUMENT', `Invalid PMID: "${pmid}"`, 'PMID must be a numeric identifier (e.g. 39088800)');
+        }
+        const xmlData = await ctx.fetchXml(buildEutilsUrl('efetch.fcgi', {
+            db: 'pubmed',
+            id: pmid,
+            rettype: 'xml',
+        }));
+        const articles = parsePubmedArticles(xmlData);
+        if (!articles.length) {
+            throw new CliError('NOT_FOUND', `Article PMID ${pmid} not found`, 'Check that the PMID is correct');
+        }
+        return articles;
+    },
+});

package/dist/clis/pubmed/info.yaml

@@ -0,0 +1,22 @@
+site: pubmed
+name: info
+description: PubMed database statistics
+database: pubmed
+strategy: public
+
+pipeline:
+  - fetch:
+      url: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi
+      params:
+        db: pubmed
+        retmode: json
+
+  - select: einforesult.dbinfo
+
+  - map:
+      database: ${{ item.dbname }}
+      description: ${{ item.description }}
+      count: ${{ item.count }}
+      last_update: ${{ item.lastupdate }}
+
+columns: [database, description, count, last_update]

package/dist/clis/pubmed/related.d.ts

@@ -0,0 +1,7 @@
+/**
+ * pubmed/related — Find related articles for a given PubMed article.
+ *
+ * Uses elink with linkname 'pubmed_pubmed' to discover related PMIDs
+ * (NCBI's pre-computed similarity), then efetch for article metadata.
+ */
+export {};

package/dist/clis/pubmed/related.js

@@ -0,0 +1,81 @@
+/**
+ * pubmed/related — Find related articles for a given PubMed article.
+ *
+ * Uses elink with linkname 'pubmed_pubmed' to discover related PMIDs
+ * (NCBI's pre-computed similarity), then efetch for article metadata.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { parsePubmedArticles } from '../_shared/xml-helpers.js';
+import { clamp } from '../_shared/common.js';
+import { isRecord } from '../../utils.js';
+cli({
+    site: 'pubmed',
+    name: 'related',
+    description: 'Find related PubMed articles',
+    database: 'pubmed',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'pmid', positional: true, required: true, help: 'PubMed ID' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max results (1-100)' },
+    ],
+    columns: ['pmid', 'title', 'authors', 'journal', 'year', 'doi'],
+    func: async (ctx, args) => {
+        const pmid = String(args.pmid).trim();
+        if (!/^\d+$/.test(pmid)) {
+            throw new CliError('ARGUMENT', `Invalid PMID: "${pmid}"`, 'PMID must be a numeric identifier');
+        }
+        const limit = clamp(Number(args.limit), 1, 100);
+        // Step 1: elink to get related PMIDs
+        const linkResult = await ctx.fetchJson(buildEutilsUrl('elink.fcgi', {
+            dbfrom: 'pubmed',
+            db: 'pubmed',
+            id: pmid,
+            linkname: 'pubmed_pubmed',
+            retmode: 'json',
+        }));
+        // Navigate elink JSON response
+        const linksets = linkResult?.linksets;
+        if (!Array.isArray(linksets) || !linksets.length) {
+            throw new CliError('NOT_FOUND', `No related articles found for PMID ${pmid}`, 'Try a different article');
+        }
+        const firstLinkset = linksets[0];
+        const linksetdbs = firstLinkset?.linksetdbs;
+        if (!Array.isArray(linksetdbs) || !linksetdbs.length) {
+            throw new CliError('NOT_FOUND', `No related articles found for PMID ${pmid}`, 'Try a different article');
+        }
+        // Find the correct linksetdb entry
+        let relatedIds = [];
+        for (const lsdb of linksetdbs) {
+            if (!isRecord(lsdb))
+                continue;
+            const links = lsdb.links;
+            if (Array.isArray(links) && links.length > 0) {
+                relatedIds = links.map(String);
+                break;
+            }
+        }
+        if (!relatedIds.length) {
+            throw new CliError('NOT_FOUND', `No related articles found for PMID ${pmid}`, 'Try a different article');
+        }
+        // Exclude the queried PMID itself from results
+        relatedIds = relatedIds.filter((id) => id !== pmid);
+        // Trim to requested limit
+        const trimmedIds = relatedIds.slice(0, limit);
+        if (!trimmedIds.length) {
+            throw new CliError('NOT_FOUND', `No related articles found for PMID ${pmid}`, 'Try a different article');
+        }
+        // Step 2: efetch those PMIDs
+        const xmlData = await ctx.fetchXml(buildEutilsUrl('efetch.fcgi', {
+            db: 'pubmed',
+            id: trimmedIds.join(','),
+            rettype: 'xml',
+        }));
+        const articles = parsePubmedArticles(xmlData);
+        if (!articles.length) {
+            throw new CliError('PARSE_ERROR', 'Failed to parse related articles', 'Try again later');
+        }
+        return articles;
+    },
+});

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

@@ -0,0 +1,8 @@
+/**
+ * pubmed/search — Search PubMed articles.
+ *
+ * Uses the two-step esearch + efetch pattern:
+ *   1. esearch to retrieve matching PMIDs
+ *   2. efetch (XML) to get full article metadata
+ */
+export {};

package/dist/clis/pubmed/search.js

@@ -0,0 +1,63 @@
+/**
+ * pubmed/search — Search PubMed articles.
+ *
+ * Uses the two-step esearch + efetch pattern:
+ *   1. esearch to retrieve matching PMIDs
+ *   2. efetch (XML) to get full article metadata
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+import { parsePubmedArticles } from '../_shared/xml-helpers.js';
+import { clamp } from '../_shared/common.js';
+import { withMeta } from '../../types.js';
+const SORT_MAP = {
+    relevance: 'relevance',
+    date: 'pub_date',
+    author: 'author',
+    journal: 'journal',
+};
+cli({
+    site: 'pubmed',
+    name: 'search',
+    description: 'Search PubMed articles',
+    database: 'pubmed',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search query (e.g. "CRISPR cancer therapy")' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max results (1-200)' },
+        { name: 'sort', default: 'relevance', choices: ['relevance', 'date', 'author', 'journal'], help: 'Sort order' },
+    ],
+    columns: ['pmid', 'title', 'authors', 'journal', 'year', 'doi'],
+    func: async (ctx, args) => {
+        const limit = clamp(Number(args.limit), 1, 200);
+        const sort = SORT_MAP[String(args.sort)] ?? 'relevance';
+        // Step 1: esearch to get PMIDs
+        const searchResult = await ctx.fetchJson(buildEutilsUrl('esearch.fcgi', {
+            db: 'pubmed',
+            term: String(args.query),
+            retmax: String(limit),
+            sort,
+            retmode: 'json',
+        }));
+        const query = String(args.query);
+        const result = searchResult;
+        const esearchResult = result?.esearchresult;
+        const pmids = esearchResult?.idlist ?? [];
+        const totalCount = Number(esearchResult?.count ?? 0);
+        if (!pmids.length) {
+            throw new CliError('NOT_FOUND', 'No articles found', 'Try different search terms or check PubMed query syntax');
+        }
+        // Step 2: efetch to get full article details (XML only for PubMed)
+        const xmlData = await ctx.fetchXml(buildEutilsUrl('efetch.fcgi', {
+            db: 'pubmed',
+            id: pmids.join(','),
+            rettype: 'xml',
+        }));
+        const articles = parsePubmedArticles(xmlData);
+        if (!articles.length) {
+            throw new CliError('PARSE_ERROR', 'Failed to parse PubMed response', 'This may be a temporary issue; try again');
+        }
+        return withMeta(articles, { totalCount, query });
+    },
+});

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

@@ -0,0 +1,7 @@
+/**
+ * snp/lookup — Look up SNP details by rsID.
+ *
+ * Uses esummary (JSON mode) directly with the numeric SNP ID
+ * to retrieve variant metadata from dbSNP.
+ */
+export {};

package/dist/clis/snp/lookup.js

@@ -0,0 +1,57 @@
+/**
+ * snp/lookup — Look up SNP details by rsID.
+ *
+ * Uses esummary (JSON mode) directly with the numeric SNP ID
+ * to retrieve variant metadata from dbSNP.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { buildEutilsUrl } from '../_shared/eutils.js';
+cli({
+    site: 'snp',
+    name: 'lookup',
+    description: 'Look up SNP details by rsID',
+    database: 'snp',
+    strategy: Strategy.PUBLIC,
+    args: [
+        { name: 'rsid', positional: true, required: true, help: 'dbSNP rsID (e.g. rs334, rs7412, rs429358)' },
+    ],
+    columns: ['rsid', 'gene', 'chromosome', 'position', 'alleles', 'maf', 'clinical', 'function'],
+    func: async (ctx, args) => {
+        const rsid = String(args.rsid).toLowerCase();
+        // Strip 'rs' prefix if present for the search, keep for display
+        const numericId = rsid.replace(/^rs/, '');
+        // esummary with SNP ID
+        const summary = await ctx.fetchJson(buildEutilsUrl('esummary.fcgi', {
+            db: 'snp', id: numericId, retmode: 'json',
+        }));
+        const uids = summary?.result?.uids ?? [];
+        if (!uids.length)
+            throw new CliError('NOT_FOUND', `SNP rs${numericId} not found`);
+        const item = summary.result[uids[0]] ?? {};
+        // dbSNP esummary fields: snp_id, genes (array), chrpos, docsum, global_mafs, clinical_significance
+        const genes = Array.isArray(item.genes) ? item.genes.map((g) => g.name).join(', ') : '';
+        const chrpos = item.chrpos ?? '';
+        const [chr, pos] = chrpos.includes(':') ? chrpos.split(':') : ['', ''];
+        // Parse MAF from docsum or global_mafs
+        const mafs = Array.isArray(item.global_mafs)
+            ? item.global_mafs.map((m) => `${m.study}:${m.freq}`).join('; ')
+            : '';
+        const clinical = Array.isArray(item.clinical_significance)
+            ? item.clinical_significance.join(', ')
+            : String(item.clinical_significance ?? '');
+        const funcAnnot = Array.isArray(item.fxn_class)
+            ? item.fxn_class.join(', ')
+            : String(item.fxn_class ?? '');
+        return [{
+                rsid: `rs${item.snp_id ?? numericId}`,
+                gene: genes,
+                chromosome: chr,
+                position: pos,
+                alleles: item.docsum ?? '',
+                maf: mafs.slice(0, 50) + (mafs.length > 50 ? '...' : ''),
+                clinical,
+                function: funcAnnot,
+            }];
+    },
+});

package/dist/clis/sra/download.d.ts

@@ -0,0 +1,18 @@
+/**
+ * sra/download — Download FASTQ files for an SRA run.
+ *
+ * Two download strategies:
+ *   1. ENA HTTPS (default, no external tools needed):
+ *      https://ftp.sra.ebi.ac.uk/vol1/fastq/SRR123/SRR1234567/SRR1234567_1.fastq.gz
+ *
+ *   2. sra-tools (fallback, requires prefetch + fasterq-dump):
+ *      prefetch SRR1234567 && fasterq-dump SRR1234567
+ *
+ * ENA is preferred because it downloads compressed FASTQ directly
+ * without needing sra-tools installed.
+ */
+/** Build ENA FASTQ download URLs for an SRR accession. */
+export declare function buildEnaFastqUrls(accession: string): string[];
+/** Parse a human-readable size string (e.g. "500M", "2G") to bytes. */
+export declare function parseMaxSize(value: string): number;
+export declare function formatSize(bytes: number): string;

package/dist/clis/sra/download.js

@@ -0,0 +1,217 @@
+/**
+ * sra/download — Download FASTQ files for an SRA run.
+ *
+ * Two download strategies:
+ *   1. ENA HTTPS (default, no external tools needed):
+ *      https://ftp.sra.ebi.ac.uk/vol1/fastq/SRR123/SRR1234567/SRR1234567_1.fastq.gz
+ *
+ *   2. sra-tools (fallback, requires prefetch + fasterq-dump):
+ *      prefetch SRR1234567 && fasterq-dump SRR1234567
+ *
+ * ENA is preferred because it downloads compressed FASTQ directly
+ * without needing sra-tools installed.
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { mkdirSync, existsSync, createWriteStream } from 'node:fs';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { execSync } from 'node:child_process';
+/** Build ENA FASTQ download URLs for an SRR accession. */
+export function buildEnaFastqUrls(accession) {
+    // ENA URL pattern: /vol1/fastq/SRR123/[NNN/]SRR1234567/
+    // Sub-directory depends on total accession length:
+    //   <= 9 chars (e.g. SRR039885):  no sub-directory
+    //   10 chars  (e.g. SRR1039508): /00N/ where N = last digit
+    //   11 chars  (e.g. SRR10395085): /0NN/ where NN = last 2 digits
+    //   >= 12 chars: /NNN/ where NNN = last 3 digits
+    const prefix = accession.slice(0, 6); // e.g. SRR103
+    let subDir = '';
+    if (accession.length === 10) {
+        subDir = `/00${accession.slice(-1)}`;
+    }
+    else if (accession.length === 11) {
+        subDir = `/0${accession.slice(-2)}`;
+    }
+    else if (accession.length >= 12) {
+        subDir = `/${accession.slice(-3)}`;
+    }
+    const base = `https://ftp.sra.ebi.ac.uk/vol1/fastq/${prefix}${subDir}/${accession}`;
+    return [
+        `${base}/${accession}.fastq.gz`, // single-end
+        `${base}/${accession}_1.fastq.gz`, // paired-end read 1
+        `${base}/${accession}_2.fastq.gz`, // paired-end read 2
+    ];
+}
+/** Check if a command exists on PATH. */
+function commandExists(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Download a file. Returns { ok, size, notFound } to distinguish 404 from real errors. */
+async function downloadFile(url, destPath) {
+    const response = await fetch(url);
+    if (response.status === 404) {
+        return { ok: false, size: 0, notFound: true };
+    }
+    if (!response.ok || !response.body) {
+        return { ok: false, size: 0, notFound: false };
+    }
+    const writable = createWriteStream(destPath);
+    await pipeline(Readable.fromWeb(response.body), writable);
+    const contentLength = response.headers.get('content-length');
+    return { ok: true, size: contentLength ? Number(contentLength) : 0, notFound: false };
+}
+/** Parse a human-readable size string (e.g. "500M", "2G") to bytes. */
+export function parseMaxSize(value) {
+    const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*([KMGT]?)B?$/i);
+    if (!match)
+        return NaN;
+    const num = parseFloat(match[1]);
+    const unit = (match[2] || '').toUpperCase();
+    const multipliers = { '': 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 };
+    return num * (multipliers[unit] ?? 1);
+}
+export function formatSize(bytes) {
+    if (bytes === 0)
+        return 'unknown size';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+cli({
+    site: 'sra',
+    name: 'download',
+    description: 'Download FASTQ files for an SRA run (via ENA or sra-tools)',
+    database: 'sra',
+    strategy: Strategy.PUBLIC,
+    timeoutSeconds: 600,
+    args: [
+        { name: 'accession', positional: true, required: true, help: 'SRA run accession (e.g. SRR1234567)' },
+        { name: 'outdir', default: '.', help: 'Output directory (default: current directory)' },
+        { name: 'method', default: 'ena', choices: ['ena', 'sra-tools'], help: 'Download method' },
+        { name: 'dry-run', type: 'boolean', default: false, help: 'Show download URLs without downloading' },
+        { name: 'max-size', help: 'Max file size to download (e.g. "500M", "2G"). Larger files are skipped.' },
+    ],
+    columns: ['file', 'size', 'status'],
+    func: async (_ctx, args) => {
+        const accession = String(args.accession).trim();
+        const outdir = String(args.outdir);
+        const method = String(args.method);
+        const dryRun = Boolean(args['dry-run']);
+        const maxSizeStr = args['max-size'] ? String(args['max-size']) : undefined;
+        const maxSizeBytes = maxSizeStr ? parseMaxSize(maxSizeStr) : Infinity;
+        if (maxSizeStr && Number.isNaN(maxSizeBytes)) {
+            throw new CliError('ARGUMENT', `Invalid --max-size value: "${maxSizeStr}"`, 'Use format like "500M", "2G", "1024K"');
+        }
+        if (!/^[SDE]RR\d+$/i.test(accession)) {
+            throw new CliError('ARGUMENT', `Invalid SRA run accession: "${accession}"`, 'Use a run accession starting with SRR, ERR, or DRR (e.g. SRR1234567)');
+        }
+        if (!existsSync(outdir)) {
+            mkdirSync(outdir, { recursive: true });
+        }
+        // Method 1: ENA HTTPS download
+        if (method === 'ena') {
+            const urls = buildEnaFastqUrls(accession);
+            const rows = [];
+            const errors = [];
+            for (const url of urls) {
+                const fileName = url.split('/').pop();
+                const destPath = join(outdir, fileName);
+                // Dry-run: probe with HEAD, report URL and size without downloading
+                if (dryRun) {
+                    try {
+                        const head = await fetch(url, { method: 'HEAD' });
+                        if (head.ok) {
+                            const size = Number(head.headers.get('content-length') ?? 0);
+                            rows.push({ file: fileName, size: formatSize(size), status: `→ ${url}` });
+                        }
+                        // 404 → skip silently (expected for single/paired mismatch)
+                    }
+                    catch { /* skip */ }
+                    continue;
+                }
+                try {
+                    // Max-size check: HEAD request first to get size
+                    if (maxSizeBytes < Infinity) {
+                        const head = await fetch(url, { method: 'HEAD' });
+                        if (head.status === 404)
+                            continue; // expected
+                        if (!head.ok) {
+                            errors.push(`${fileName}: HTTP ${head.status}`);
+                            rows.push({ file: fileName, size: '', status: 'failed' });
+                            continue;
+                        }
+                        const size = Number(head.headers.get('content-length') ?? 0);
+                        if (size > maxSizeBytes) {
+                            rows.push({ file: fileName, size: formatSize(size), status: `skipped (exceeds --max-size ${maxSizeStr})` });
+                            continue;
+                        }
+                    }
+                    const result = await downloadFile(url, destPath);
+                    if (result.ok) {
+                        rows.push({ file: fileName, size: formatSize(result.size), status: `saved → ${destPath}` });
+                    }
+                    else if (!result.notFound) {
+                        errors.push(`${fileName}: HTTP error`);
+                        rows.push({ file: fileName, size: '', status: 'failed' });
+                    }
+                    // 404 is expected: single-end has no _1/_2, paired-end has no plain .fastq.gz
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    errors.push(`${fileName}: ${msg}`);
+                    rows.push({ file: fileName, size: '', status: `error: ${msg}` });
+                }
+            }
+            if (dryRun) {
+                if (!rows.length) {
+                    throw new CliError('NOT_FOUND', `FASTQ files not available on ENA for ${accession}`);
+                }
+                return rows;
+            }
+            const successCount = rows.filter(r => r.status.startsWith('saved')).length;
+            if (successCount === 0) {
+                throw new CliError('NOT_FOUND', `FASTQ files not available on ENA for ${accession}`, 'The run may not be mirrored to ENA yet. Try: biocli sra download ' + accession + ' --method sra-tools');
+            }
+            if (errors.length > 0) {
+                throw new CliError('API_ERROR', `Partial download failure for ${accession}: ${errors.join('; ')}`, 'Some files failed to download. Check network connectivity and retry.');
+            }
+            return rows;
+        }
+        // Method 2: sra-tools
+        if (!commandExists('prefetch')) {
+            throw new CliError('ARGUMENT', 'sra-tools not found on PATH', 'Install sra-tools: conda install -c bioconda sra-tools, or use --method ena');
+        }
+        const rows = [];
+        try {
+            // prefetch downloads the .sra file
+            console.error(`Downloading ${accession} with prefetch...`);
+            execSync(`prefetch ${accession} -O "${outdir}"`, { stdio: 'inherit' });
+            rows.push({ file: `${accession}.sra`, size: '', status: 'prefetch done' });
+            // fasterq-dump converts .sra to .fastq
+            if (commandExists('fasterq-dump')) {
+                console.error(`Converting to FASTQ with fasterq-dump...`);
+                execSync(`fasterq-dump "${join(outdir, accession)}" -O "${outdir}" --split-files`, { stdio: 'inherit' });
+                rows.push({ file: `${accession}*.fastq`, size: '', status: 'fasterq-dump done' });
+            }
+            else {
+                rows.push({ file: '', size: '', status: 'fasterq-dump not found — .sra file downloaded only' });
+            }
+        }
+        catch (err) {
+            throw new CliError('API_ERROR', `sra-tools failed: ${err instanceof Error ? err.message : String(err)}`, 'Check that sra-tools is correctly configured');
+        }
+        return rows;
+    },
+});

package/dist/clis/sra/run.d.ts

@@ -0,0 +1,8 @@
+/**
+ * sra/run — Get SRA run details by accession.
+ *
+ * Searches for a single SRA accession (SRR, SRX, SRP, etc.) and
+ * retrieves detailed run metadata via esummary (JSON). Parses the
+ * embedded XML strings in expxml/runs fields.
+ */
+export {};