@yangfei_93sky/biocli 0.2.0

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI entry point: registers built-in commands and wires up Commander.
+ *
+ * Built-in commands are registered inline here (list, validate, config, etc.).
+ * Dynamic adapter commands are registered via commander-adapter.ts.
+ */
+export declare function runCli(): void;

package/dist/cli.js

@@ -0,0 +1,336 @@
+/**
+ * CLI entry point: registers built-in commands and wires up Commander.
+ *
+ * Built-in commands are registered inline here (list, validate, config, etc.).
+ * Dynamic adapter commands are registered via commander-adapter.ts.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { fullName, getRegistry, strategyLabel } from './registry.js';
+import { render as renderOutput } from './output.js';
+import { getVersion } from './version.js';
+import { printCompletionScript, getCompletions } from './completion.js';
+import { registerAllCommands } from './commander-adapter.js';
+import { validateAll } from './validate.js';
+import { runDoctor, formatDoctorText, formatDoctorJson } from './doctor.js';
+import { biocliResultSchema, resultWithMetaSchema } from './schema.js';
+import { runVerify, formatVerifyText, formatVerifyJson } from './verify.js';
+import { loadConfig, saveConfig, getConfigPath } from './config.js';
+import { getStats as getCacheStats, clearCache } from './cache.js';
+import { BUILTIN_CLIS_DIR, USER_CLIS_DIR } from './discovery.js';
+export function runCli() {
+    const program = new Command();
+    const version = getVersion();
+    program
+        .name('biocli')
+        .description('Query biological databases from the terminal')
+        .version(version)
+        .enablePositionalOptions()
+        .addHelpText('before', `
+  ${chalk.bold.cyan('biocli')} ${chalk.dim(`v${version}`)}  ${chalk.dim('─')}  Query biological databases from the terminal
+  ${chalk.dim('NCBI · UniProt · KEGG · STRING · Ensembl · Enrichr')}
+`)
+        .addHelpText('after', `
+${chalk.bold('Examples:')}
+  ${chalk.cyan('biocli pubmed search "CRISPR cancer"')}       Search PubMed articles
+  ${chalk.cyan('biocli pubmed fetch 30684591')}               Get article details by PMID
+  ${chalk.cyan('biocli gene search TP53')}                    Search genes
+  ${chalk.cyan('biocli gene info 7157')}                      Gene details by ID
+  ${chalk.cyan('biocli geo search "breast cancer RNA-seq"')}  Search GEO datasets
+  ${chalk.cyan('biocli sra search "CRISPR human"')}           Search SRA runs
+  ${chalk.cyan('biocli clinvar search BRCA1')}                Search clinical variants
+  ${chalk.cyan('biocli snp lookup rs334')}                    Look up SNP by rsID
+  ${chalk.cyan('biocli taxonomy lookup "Homo sapiens"')}      Taxonomy lookup
+
+${chalk.bold('Output formats:')}
+  -f table ${chalk.dim('(default)')}    -f json     -f csv
+  -f yaml                -f md       -f plain
+
+${chalk.bold('Configuration:')}
+  ${chalk.cyan('biocli config set api_key YOUR_KEY')}   Set NCBI API key (increases rate limit to 10 req/s)
+  ${chalk.cyan('biocli config set email you@example.com')}
+  ${chalk.cyan('biocli config show')}                   Show current config
+`);
+    // ── Hidden: shell completion data endpoint ──────────────────────────────
+    program
+        .option('--get-completions', 'Internal: return completion candidates')
+        .option('--cursor <n>', 'Internal: cursor position for completions');
+    // ── Built-in: list ────────────────────────────────────────────────────────
+    program
+        .command('list')
+        .description('List all available CLI commands')
+        .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
+        .option('--json', 'JSON output (shorthand)')
+        .action((opts) => {
+        const registry = getRegistry();
+        const commands = [...new Set(registry.values())].sort((a, b) => fullName(a).localeCompare(fullName(b)));
+        const fmt = opts.json && opts.format === 'table' ? 'json' : opts.format;
+        if (fmt !== 'table') {
+            const downloadNames = new Set(['download', 'fetch', 'sequence']);
+            const rows = commands.map(c => {
+                const tags = [];
+                if (c.database === 'aggregate')
+                    tags.push('workflow');
+                else if (downloadNames.has(c.name))
+                    tags.push('download');
+                else
+                    tags.push('query');
+                return {
+                    command: fullName(c),
+                    site: c.site,
+                    name: c.name,
+                    aliases: c.aliases?.join(', ') ?? '',
+                    description: c.description,
+                    strategy: strategyLabel(c),
+                    database: c.database ?? '',
+                    args: c.args.map(a => ({
+                        name: a.name,
+                        ...(a.type ? { type: a.type } : {}),
+                        ...(a.required ? { required: true } : {}),
+                        ...(a.positional ? { positional: true } : {}),
+                        ...(a.default !== undefined ? { default: a.default } : {}),
+                        ...(a.choices ? { choices: a.choices } : {}),
+                        ...(a.help ? { help: a.help } : {}),
+                    })),
+                    defaultFormat: c.defaultFormat ?? 'table',
+                    columns: c.columns ?? [],
+                    tags,
+                };
+            });
+            renderOutput(rows, {
+                fmt,
+                columns: ['command', 'site', 'name', 'aliases', 'description', 'strategy', 'database'],
+                title: 'biocli/list',
+                source: 'biocli list',
+            });
+            return;
+        }
+        // Table (default) — grouped by site
+        const sites = new Map();
+        for (const cmd of commands) {
+            const g = sites.get(cmd.site) ?? [];
+            g.push(cmd);
+            sites.set(cmd.site, g);
+        }
+        console.log();
+        console.log(chalk.bold('  biocli') + chalk.dim(' — available commands'));
+        console.log();
+        for (const [site, cmds] of sites) {
+            console.log(chalk.bold.cyan(`  ${site}`));
+            for (const cmd of cmds) {
+                const label = strategyLabel(cmd);
+                const tag = label === 'public'
+                    ? chalk.green('[public]')
+                    : chalk.yellow(`[${label}]`);
+                const aliases = cmd.aliases?.length ? chalk.dim(` (aliases: ${cmd.aliases.join(', ')})`) : '';
+                const db = cmd.database ? chalk.dim(` [${cmd.database}]`) : '';
+                console.log(`    ${cmd.name} ${tag}${db}${aliases}${cmd.description ? chalk.dim(` — ${cmd.description}`) : ''}`);
+            }
+            console.log();
+        }
+        console.log(chalk.dim(`  ${commands.length} commands total`));
+    });
+    // ── Built-in: validate ────────────────────────────────────────────────────
+    program
+        .command('validate')
+        .description('Validate YAML adapter definitions')
+        .option('-d, --dir <path>', 'Directory to validate', BUILTIN_CLIS_DIR)
+        .action((opts) => {
+        const dirs = [opts.dir];
+        // Also check user CLIs if they exist
+        try {
+            const { existsSync } = require('node:fs');
+            if (existsSync(USER_CLIS_DIR))
+                dirs.push(USER_CLIS_DIR);
+        }
+        catch { /* ignore */ }
+        let totalErrors = 0;
+        for (const dir of dirs) {
+            const results = validateAll(dir);
+            if (results.length === 0) {
+                console.log(chalk.green(`All YAML definitions in ${dir} are valid.`));
+                continue;
+            }
+            for (const result of results) {
+                console.error(chalk.red(`\n${result.file}:`));
+                for (const error of result.errors) {
+                    console.error(chalk.yellow(`  - ${error}`));
+                }
+                totalErrors += result.errors.length;
+            }
+        }
+        if (totalErrors > 0) {
+            console.error(chalk.red(`\n${totalErrors} validation error(s) found.`));
+            process.exitCode = 1;
+        }
+    });
+    // ── Built-in: config ──────────────────────────────────────────────────────
+    const configCmd = program
+        .command('config')
+        .description('Manage biocli configuration');
+    configCmd
+        .command('show')
+        .description('Show current configuration')
+        .option('-f, --format <fmt>', 'Output format: table, json, yaml', 'yaml')
+        .action((opts) => {
+        const config = loadConfig();
+        // Mask API key for display
+        const display = { ...config };
+        if (display.api_key) {
+            display.api_key = display.api_key.slice(0, 4) + '****' + display.api_key.slice(-4);
+        }
+        renderOutput([display], { fmt: opts.format, title: 'biocli/config' });
+    });
+    configCmd
+        .command('set <key> <value>')
+        .description('Set a configuration value (api_key, email, defaults.format, defaults.limit)')
+        .action((key, value) => {
+        const config = loadConfig();
+        if (key === 'api_key' || key === 'email') {
+            config[key] = value;
+        }
+        else if (key === 'defaults.format') {
+            config.defaults = config.defaults ?? {};
+            config.defaults.format = value;
+        }
+        else if (key === 'defaults.limit') {
+            config.defaults = config.defaults ?? {};
+            config.defaults.limit = parseInt(value, 10);
+            if (isNaN(config.defaults.limit)) {
+                console.error(chalk.red(`Invalid limit value: "${value}". Must be a number.`));
+                process.exitCode = 1;
+                return;
+            }
+        }
+        else if (key === 'cache.enabled') {
+            config.cache = config.cache ?? {};
+            config.cache.enabled = value.toLowerCase() === 'true' || value === '1';
+        }
+        else if (key === 'cache.ttl') {
+            config.cache = config.cache ?? {};
+            config.cache.ttl = parseInt(value, 10);
+            if (isNaN(config.cache.ttl) || config.cache.ttl <= 0) {
+                console.error(chalk.red(`Invalid cache TTL: "${value}". Must be a positive number (hours).`));
+                process.exitCode = 1;
+                return;
+            }
+        }
+        else {
+            console.error(chalk.red(`Unknown config key: "${key}".`));
+            console.error(chalk.dim('Valid keys: api_key, email, defaults.format, defaults.limit, cache.enabled, cache.ttl'));
+            process.exitCode = 1;
+            return;
+        }
+        saveConfig(config);
+        console.log(chalk.green(`Set ${key} = ${key === 'api_key' ? '****' : value}`));
+    });
+    configCmd
+        .command('path')
+        .description('Show configuration file path')
+        .action(() => {
+        console.log(getConfigPath());
+    });
+    // ── Built-in: completion ──────────────────────────────────────────────────
+    program
+        .command('completion [shell]')
+        .description('Output shell completion script (bash, zsh, fish)')
+        .action((shell) => {
+        printCompletionScript(shell ?? 'bash');
+    });
+    // ── Built-in: schema ───────────────────────────────────────────────────────
+    program
+        .command('schema [type]')
+        .description('Output JSON Schema for biocli result types (default: result, or: meta)')
+        .action((type) => {
+        const schema = type === 'meta' ? resultWithMetaSchema : biocliResultSchema;
+        console.log(JSON.stringify(schema, null, 2));
+    });
+    // ── Built-in: doctor ───────────────────────────────────────────────────────
+    program
+        .command('doctor')
+        .description('Diagnose biocli configuration and backend connectivity')
+        .option('-f, --format <fmt>', 'Output format: text, json', 'text')
+        .action(async (opts) => {
+        const { checks, allPassed } = await runDoctor();
+        if (opts.format === 'json') {
+            console.log(formatDoctorJson(checks, allPassed));
+        }
+        else {
+            console.log(formatDoctorText(checks, allPassed));
+        }
+        if (!allPassed)
+            process.exitCode = 1;
+    });
+    // ── Built-in: verify ───────────────────────────────────────────────────────
+    program
+        .command('verify')
+        .description('Run all checks: validate + doctor (+ optional smoke)')
+        .option('--smoke', 'Also run core smoke tests')
+        .option('-f, --format <fmt>', 'Output format: text, json', 'text')
+        .action(async (opts) => {
+        const result = await runVerify({ smoke: opts.smoke });
+        if (opts.format === 'json') {
+            console.log(formatVerifyJson(result));
+        }
+        else {
+            console.log(formatVerifyText(result));
+        }
+        if (!result.allPassed)
+            process.exitCode = 1;
+    });
+    // ── Built-in: cache ────────────────────────────────────────────────────────
+    const cacheCmd = program
+        .command('cache')
+        .description('Manage local response cache');
+    cacheCmd
+        .command('stats')
+        .description('Show cache statistics')
+        .option('-f, --format <fmt>', 'Output format: text, json', 'text')
+        .action((opts) => {
+        const stats = getCacheStats();
+        if (opts.format === 'json') {
+            console.log(JSON.stringify(stats, null, 2));
+        }
+        else {
+            console.log();
+            console.log(chalk.bold('  biocli cache stats'));
+            console.log();
+            console.log(`  Entries     ${stats.totalEntries}`);
+            console.log(`  Size        ${(stats.totalSizeBytes / 1024).toFixed(1)} KB`);
+            if (stats.oldestEntry)
+                console.log(`  Oldest      ${stats.oldestEntry}`);
+            if (stats.newestEntry)
+                console.log(`  Newest      ${stats.newestEntry}`);
+            if (Object.keys(stats.databases).length > 0) {
+                console.log(`  Databases   ${Object.entries(stats.databases).map(([k, v]) => `${k}(${v})`).join(', ')}`);
+            }
+            console.log();
+        }
+    });
+    cacheCmd
+        .command('clear')
+        .description('Clear all cached responses')
+        .action(() => {
+        const count = clearCache();
+        console.log(chalk.green(`Cleared ${count} cache entries.`));
+    });
+    // ── Register dynamic adapter commands ─────────────────────────────────────
+    registerAllCommands(program);
+    // ── Handle hidden --get-completions flag ─────────────────────────────────
+    const rawArgs = process.argv.slice(2);
+    if (rawArgs.includes('--get-completions')) {
+        const cursorIdx = rawArgs.indexOf('--cursor');
+        const cursor = cursorIdx >= 0 ? parseInt(rawArgs[cursorIdx + 1], 10) : 1;
+        const words = rawArgs.filter((a, i) => a !== '--get-completions' && i !== cursorIdx && i !== cursorIdx + 1);
+        const candidates = getCompletions(words, cursor);
+        if (candidates.length > 0) {
+            process.stdout.write(candidates.join('\n') + '\n');
+        }
+        return;
+    }
+    // ── Parse and execute ────────────────────────────────────────────────────���
+    program.parseAsync(process.argv).catch((err) => {
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+    });
+}

package/dist/clis/_shared/common.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Common utility functions shared across NCBI adapter commands.
+ */
+export { clamp } from '../../utils.js';
+/**
+ * Truncate a string to `maxLen` characters, appending '...' if trimmed.
+ */
+export declare function truncate(text: string, maxLen: number): string;

package/dist/clis/_shared/common.js

@@ -0,0 +1,13 @@
+/**
+ * Common utility functions shared across NCBI adapter commands.
+ */
+// Re-export clamp from the core utils module.
+export { clamp } from '../../utils.js';
+/**
+ * Truncate a string to `maxLen` characters, appending '...' if trimmed.
+ */
+export function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + '...';
+}

package/dist/clis/_shared/eutils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared E-utilities helpers for NCBI adapter commands.
+ *
+ * Re-exports the core buildEutilsUrl from ncbi-fetch so that adapter
+ * files can import from a short, consistent path:
+ *
+ *   import { buildEutilsUrl, EUTILS_BASE } from '../_shared/eutils.js';
+ */
+export { EUTILS_BASE, buildEutilsUrl } from '../../ncbi-fetch.js';

package/dist/clis/_shared/eutils.js

@@ -0,0 +1,9 @@
+/**
+ * Shared E-utilities helpers for NCBI adapter commands.
+ *
+ * Re-exports the core buildEutilsUrl from ncbi-fetch so that adapter
+ * files can import from a short, consistent path:
+ *
+ *   import { buildEutilsUrl, EUTILS_BASE } from '../_shared/eutils.js';
+ */
+export { EUTILS_BASE, buildEutilsUrl } from '../../ncbi-fetch.js';

package/dist/clis/_shared/organism-db.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Unified organism database for cross-database ID resolution.
+ *
+ * Maps common organism names to identifiers used by each database:
+ *   - NCBI taxonomy name and ID
+ *   - KEGG organism code
+ *   - Ensembl species name
+ */
+export interface OrganismEntry {
+    name: string;
+    taxId: number;
+    keggOrg: string;
+    ensemblName: string;
+}
+export declare const ORGANISM_DB: Record<string, OrganismEntry>;
+/**
+ * Resolve an organism identifier (common name, scientific name, taxId, or KEGG code)
+ * to a full OrganismEntry.
+ *
+ * Throws if the organism is not recognized — never silently defaults to human,
+ * because that would produce scientifically wrong cross-database queries.
+ */
+export declare function resolveOrganism(input: string): OrganismEntry;

package/dist/clis/_shared/organism-db.js

@@ -0,0 +1,58 @@
+/**
+ * Unified organism database for cross-database ID resolution.
+ *
+ * Maps common organism names to identifiers used by each database:
+ *   - NCBI taxonomy name and ID
+ *   - KEGG organism code
+ *   - Ensembl species name
+ */
+import { ArgumentError } from '../../errors.js';
+export const ORGANISM_DB = {
+    human: { name: 'Homo sapiens', taxId: 9606, keggOrg: 'hsa', ensemblName: 'homo_sapiens' },
+    mouse: { name: 'Mus musculus', taxId: 10090, keggOrg: 'mmu', ensemblName: 'mus_musculus' },
+    rat: { name: 'Rattus norvegicus', taxId: 10116, keggOrg: 'rno', ensemblName: 'rattus_norvegicus' },
+    zebrafish: { name: 'Danio rerio', taxId: 7955, keggOrg: 'dre', ensemblName: 'danio_rerio' },
+    fly: { name: 'Drosophila melanogaster', taxId: 7227, keggOrg: 'dme', ensemblName: 'drosophila_melanogaster' },
+    worm: { name: 'Caenorhabditis elegans', taxId: 6239, keggOrg: 'cel', ensemblName: 'caenorhabditis_elegans' },
+    yeast: { name: 'Saccharomyces cerevisiae', taxId: 4932, keggOrg: 'sce', ensemblName: 'saccharomyces_cerevisiae' },
+    chicken: { name: 'Gallus gallus', taxId: 9031, keggOrg: 'gga', ensemblName: 'gallus_gallus' },
+    dog: { name: 'Canis lupus familiaris', taxId: 9615, keggOrg: 'cfa', ensemblName: 'canis_lupus_familiaris' },
+    pig: { name: 'Sus scrofa', taxId: 9823, keggOrg: 'ssc', ensemblName: 'sus_scrofa' },
+    cow: { name: 'Bos taurus', taxId: 9913, keggOrg: 'bta', ensemblName: 'bos_taurus' },
+    rabbit: { name: 'Oryctolagus cuniculus', taxId: 9986, keggOrg: 'ocu', ensemblName: 'oryctolagus_cuniculus' },
+    frog: { name: 'Xenopus tropicalis', taxId: 8364, keggOrg: 'xtr', ensemblName: 'xenopus_tropicalis' },
+};
+/**
+ * Resolve an organism identifier (common name, scientific name, taxId, or KEGG code)
+ * to a full OrganismEntry.
+ *
+ * Throws if the organism is not recognized — never silently defaults to human,
+ * because that would produce scientifically wrong cross-database queries.
+ */
+export function resolveOrganism(input) {
+    const lower = input.toLowerCase().trim();
+    // Direct match by common name
+    if (ORGANISM_DB[lower])
+        return ORGANISM_DB[lower];
+    // Match by scientific name
+    for (const entry of Object.values(ORGANISM_DB)) {
+        if (entry.name.toLowerCase() === lower)
+            return entry;
+    }
+    // Match by taxId
+    const taxId = parseInt(lower, 10);
+    if (!isNaN(taxId)) {
+        for (const entry of Object.values(ORGANISM_DB)) {
+            if (entry.taxId === taxId)
+                return entry;
+        }
+    }
+    // Match by KEGG org code
+    for (const entry of Object.values(ORGANISM_DB)) {
+        if (entry.keggOrg === lower)
+            return entry;
+    }
+    // Unknown organism — fail as argument error (exit code 2, not generic error)
+    const supported = Object.keys(ORGANISM_DB).join(', ');
+    throw new ArgumentError(`Unknown organism: "${input}"`, `Supported: ${supported}. Also accepts scientific names (e.g. "Homo sapiens"), taxonomy IDs (e.g. 9606), or KEGG codes (e.g. hsa).`);
+}

package/dist/clis/_shared/xml-helpers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PubMed & Gene XML parsing helpers.
+ *
+ * After fast-xml-parser processes NCBI XML (see xml-parser.ts), the
+ * result is a deeply nested JS object.  These helpers navigate that
+ * structure and return flat, typed records suitable for CLI table output.
+ *
+ * NOTE: The xml-parser config uses:
+ *   - '@_' prefix for attributes  (e.g. @_EIdType)
+ *   - '#text' for text nodes
+ *   - Tags listed in ARRAY_TAGS are always arrays (Author, PubmedArticle, etc.)
+ */
+export interface PubmedArticle {
+    pmid: string;
+    title: string;
+    authors: string;
+    journal: string;
+    year: string;
+    doi: string;
+    abstract: string;
+}
+/**
+ * Parse a PubMed efetch XML response (after fast-xml-parser processing)
+ * into an array of PubmedArticle records.
+ */
+export declare function parsePubmedArticles(parsed: unknown): PubmedArticle[];
+export interface GeneInfo {
+    geneId: string;
+    symbol: string;
+    name: string;
+    organism: string;
+    summary: string;
+    chromosome: string;
+    location: string;
+}
+/**
+ * Parse Gene esummary JSON response into GeneInfo records.
+ *
+ * The esummary JSON for the gene database has the structure:
+ * {
+ *   result: {
+ *     uids: ["7157", ...],
+ *     "7157": { uid: "7157", name: "TP53", description: "...", ... }
+ *   }
+ * }
+ */
+export declare function parseGeneSummaries(parsed: unknown): GeneInfo[];
+/**
+ * Parse Gene efetch XML response (Entrezgene-Set) into GeneInfo records.
+ *
+ * Gene efetch XML has the structure:
+ *   Entrezgene-Set > Entrezgene[] > Entrezgene_track-info > Gene-track > Gene-track_geneid
+ *   etc.
+ *
+ * This is considerably more complex than esummary, so we prefer esummary
+ * for most gene commands.  This parser is provided for completeness.
+ */
+export declare function parseGeneEntries(parsed: unknown): GeneInfo[];