@yangfei_93sky/biocli 0.2.0

package/dist/commander-adapter.js

@@ -0,0 +1,286 @@
+/**
+ * Commander adapter: bridges Registry commands to Commander subcommands.
+ *
+ * This is a THIN adapter — it only handles:
+ * 1. Commander arg/option registration
+ * 2. Collecting kwargs from Commander's action args
+ * 3. Calling executeCommand (which handles HttpContext, validation, etc.)
+ * 4. Rendering output and errors
+ *
+ * All execution logic lives in execution.ts.
+ */
+import chalk from 'chalk';
+import { parseBatchInput, mergeBatchResults } from './batch.js';
+import { fullName, getRegistry } from './registry.js';
+import { render as renderOutput } from './output.js';
+import { executeCommand } from './execution.js';
+import { startSpinner } from './spinner.js';
+import { hasResultMeta } from './types.js';
+import { CliError, EXIT_CODES, ERROR_ICONS, getErrorMessage, ArgumentError, } from './errors.js';
+// ── Arg value normalization ─────────────────────────────────────────────────
+export function normalizeArgValue(argType, value, name) {
+    if (argType !== 'bool' && argType !== 'boolean')
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    if (value == null || value === '')
+        return false;
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    throw new ArgumentError(`"${name}" must be either "true" or "false".`);
+}
+// ── Register a single command ───────────────────────────────────────────────
+/**
+ * Register a single CliCommand as a Commander subcommand.
+ */
+export function registerCommandToProgram(siteCmd, cmd) {
+    if (siteCmd.commands.some((c) => c.name() === cmd.name))
+        return;
+    const deprecatedSuffix = cmd.deprecated ? ' [deprecated]' : '';
+    const subCmd = siteCmd.command(cmd.name).description(`${cmd.description}${deprecatedSuffix}`);
+    if (cmd.aliases?.length)
+        subCmd.aliases(cmd.aliases);
+    // Register positional args first, then named options
+    // Positional args are always registered as optional with Commander —
+    // required checks are done in the action handler to allow --input batch mode
+    const positionalArgs = [];
+    for (const arg of cmd.args) {
+        if (arg.positional) {
+            subCmd.argument(`[${arg.name}]`, arg.help ?? '');
+            positionalArgs.push(arg);
+        }
+        else {
+            const flag = arg.required ? `--${arg.name} <value>` : `--${arg.name} [value]`;
+            if (arg.required)
+                subCmd.requiredOption(flag, arg.help ?? '');
+            else if (arg.default != null)
+                subCmd.option(flag, arg.help ?? '', String(arg.default));
+            else
+                subCmd.option(flag, arg.help ?? '');
+        }
+    }
+    subCmd
+        .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
+        .option('-c, --columns <cols>', 'Columns to display (comma-separated, e.g. pmid,title,abstract)')
+        .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');
+    subCmd.action(async (...actionArgs) => {
+        const actionOpts = actionArgs[positionalArgs.length] ?? {};
+        const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
+        const startTime = Date.now();
+        // ── Execute + render ────────────────────────────────────────────────
+        try {
+            // ── Collect kwargs ────────────────────────────────────────────────
+            const kwargs = {};
+            for (let i = 0; i < positionalArgs.length; i++) {
+                const v = actionArgs[i];
+                if (v !== undefined)
+                    kwargs[positionalArgs[i].name] = v;
+            }
+            for (const arg of cmd.args) {
+                if (arg.positional)
+                    continue;
+                const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
+                const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
+                if (v !== undefined)
+                    kwargs[arg.name] = normalizeArgValue(arg.type, v, arg.name);
+            }
+            const verbose = optionsRecord.verbose === true;
+            const inputFile = typeof optionsRecord.input === 'string' ? optionsRecord.input : undefined;
+            // Validate required positional args (unless --input provides batch input)
+            if (!inputFile) {
+                for (const arg of positionalArgs) {
+                    if (arg.required && (kwargs[arg.name] === undefined || kwargs[arg.name] === null || kwargs[arg.name] === '')) {
+                        console.error(chalk.red(`error: missing required argument '${arg.name}'`));
+                        process.exitCode = 1;
+                        return;
+                    }
+                }
+            }
+            let format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
+            if (verbose)
+                process.env.BIOCLI_VERBOSE = '1';
+            if (cmd.deprecated) {
+                const message = typeof cmd.deprecated === 'string' ? cmd.deprecated : `${fullName(cmd)} is deprecated.`;
+                const replacement = cmd.replacedBy ? ` Use ${cmd.replacedBy} instead.` : '';
+                console.error(chalk.yellow(`Deprecated: ${message}${replacement}`));
+            }
+            // Commander's --no-cache sets optionsRecord.cache to false
+            const noCache = optionsRecord.cache === false;
+            // ── Batch mode: --input or comma-separated positional ────────────
+            const primaryArg = positionalArgs[0]; // first positional = primary ID/query
+            const batchItems = primaryArg
+                ? parseBatchInput(kwargs[primaryArg.name], inputFile)
+                : null;
+            let result;
+            if (batchItems && primaryArg) {
+                const spinnerLabel = `Batch ${fullName(cmd)} (${batchItems.length} items)…`;
+                const spinner = startSpinner(spinnerLabel);
+                const batchResults = [];
+                const errors = [];
+                try {
+                    for (const item of batchItems) {
+                        try {
+                            const batchKwargs = { ...kwargs, [primaryArg.name]: item };
+                            const r = await executeCommand(cmd, batchKwargs, verbose, { noCache });
+                            if (r !== null && r !== undefined)
+                                batchResults.push(r);
+                        }
+                        catch (err) {
+                            errors.push(`${item}: ${err instanceof Error ? err.message : String(err)}`);
+                            if (verbose)
+                                console.error(chalk.yellow(`[Batch] ${item} failed: ${err instanceof Error ? err.message : String(err)}`));
+                        }
+                    }
+                }
+                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 (!batchResults.length) {
+                    console.error(chalk.red(`All ${batchItems.length} batch items failed.`));
+                    process.exitCode = 1;
+                    return;
+                }
+                result = mergeBatchResults(batchResults);
+            }
+            else {
+                const spinnerLabel = cmd.database
+                    ? `Querying ${cmd.database}…`
+                    : `Running ${fullName(cmd)}…`;
+                const spinner = startSpinner(spinnerLabel);
+                try {
+                    result = await executeCommand(cmd, kwargs, verbose, { noCache });
+                }
+                finally {
+                    spinner.stop();
+                }
+            }
+            if (result === null || result === undefined) {
+                return;
+            }
+            // Extract display metadata if the command returned ResultWithMeta
+            let renderData = result;
+            let totalCount;
+            let query;
+            if (hasResultMeta(result)) {
+                renderData = result.rows;
+                totalCount = result.meta.totalCount;
+                query = result.meta.query;
+            }
+            const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
+            if (format === 'table' && resolved.defaultFormat) {
+                format = resolved.defaultFormat;
+            }
+            // Auto-detect pipe: output JSON when stdout is not a terminal
+            if (format === 'table' && !process.stdout.isTTY) {
+                format = 'json';
+            }
+            if (verbose && (!renderData || (Array.isArray(renderData) && renderData.length === 0))) {
+                console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
+            }
+            // Resolve which columns to display:
+            //   --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;
+            const userColumns = typeof optionsRecord.columns === 'string' ? optionsRecord.columns : undefined;
+            if (userColumns) {
+                displayColumns = userColumns.split(',').map((s) => s.trim()).filter(Boolean);
+            }
+            else if (allColumns) {
+                // Show all fields present in the data
+                displayColumns = undefined; // output.ts will derive from row keys
+            }
+            renderOutput(renderData, {
+                fmt: format,
+                columns: displayColumns,
+                title: `${resolved.site}/${resolved.name}`,
+                elapsed: (Date.now() - startTime) / 1000,
+                source: fullName(resolved),
+                totalCount,
+                query,
+            });
+        }
+        catch (err) {
+            renderError(err, fullName(cmd), optionsRecord.verbose === true);
+            process.exitCode = resolveExitCode(err);
+        }
+    });
+}
+// ── Register all commands ───────────────────────────────────────────────────
+/**
+ * Iterate the registry, group commands by site, and register each
+ * as a Commander subcommand under a site parent command.
+ */
+export function registerAllCommands(program) {
+    const registry = getRegistry();
+    const sites = new Map();
+    // Deduplicate: skip alias entries (they point to the same CliCommand object)
+    const seen = new Set();
+    for (const [, cmd] of registry) {
+        if (seen.has(cmd))
+            continue;
+        seen.add(cmd);
+        const group = sites.get(cmd.site) ?? [];
+        group.push(cmd);
+        sites.set(cmd.site, group);
+    }
+    for (const [site, commands] of sites) {
+        // Create parent command for the site (e.g. "pubmed", "gene")
+        let siteCmd = program.commands.find(c => c.name() === site);
+        if (!siteCmd) {
+            siteCmd = program.command(site).description(`${site} commands`);
+        }
+        for (const cmd of commands) {
+            registerCommandToProgram(siteCmd, cmd);
+        }
+    }
+}
+// ── Exit code resolution ─────────────────────────────────────────────────────
+/**
+ * Map any thrown value to a Unix process exit code.
+ */
+export function resolveExitCode(err) {
+    if (err instanceof CliError)
+        return err.exitCode;
+    const msg = getErrorMessage(err);
+    const m = msg.toLowerCase();
+    if (/\b(status[: ]+)?[45]\d{2}\b|http[/ ][45]\d{2}/.test(m))
+        return EXIT_CODES.GENERIC_ERROR;
+    if (/not found|no .+ found/.test(m))
+        return EXIT_CODES.EMPTY_RESULT;
+    return EXIT_CODES.GENERIC_ERROR;
+}
+// ── Error rendering ──────────────────────────────────────────────────────────
+const ISSUES_URL = 'https://github.com/youngfly93/biocli/issues';
+function renderError(err, cmdName, verbose) {
+    if (err instanceof CliError) {
+        const icon = ERROR_ICONS[err.code] ?? '!';
+        console.error(chalk.red(`${icon} ${err.message}`));
+        if (err.hint) {
+            console.error(chalk.yellow(`  Hint: ${err.hint}`));
+        }
+        if (verbose && err.stack) {
+            console.error(chalk.dim(err.stack));
+        }
+        return;
+    }
+    // Generic error
+    const message = getErrorMessage(err);
+    console.error(chalk.red(`! Error in ${cmdName}: ${message}`));
+    if (verbose && err instanceof Error && err.stack) {
+        console.error(chalk.dim(err.stack));
+    }
+    console.error(chalk.dim(`  If this persists, please report at ${ISSUES_URL}`));
+}

package/dist/completion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shell tab-completion support for biocli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ *
+ * @param words  - The argv after 'biocli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export declare function getCompletions(words: string[], cursor: number): string[];
+export declare function generateCompletion(shell: 'bash' | 'zsh' | 'fish'): string;
+/**
+ * Print the completion script for the requested shell.
+ */
+export declare function printCompletionScript(shell: string): void;

package/dist/completion.js

@@ -0,0 +1,117 @@
+/**
+ * Shell tab-completion support for biocli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+import { getRegistry } from './registry.js';
+// ── Dynamic completion logic ───────────────────────────────────────────────
+/**
+ * Built-in (non-dynamic) top-level commands.
+ */
+const BUILTIN_COMMANDS = [
+    'list',
+    'validate',
+    'config',
+    'completion',
+];
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ *
+ * @param words  - The argv after 'biocli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export function getCompletions(words, cursor) {
+    // cursor === 1 → completing the first argument (site name or built-in command)
+    if (cursor <= 1) {
+        const sites = new Set();
+        for (const [, cmd] of getRegistry()) {
+            sites.add(cmd.site);
+        }
+        return [...BUILTIN_COMMANDS, ...sites].sort();
+    }
+    const site = words[0];
+    // If the first word is a built-in command, no further completion
+    if (BUILTIN_COMMANDS.includes(site)) {
+        // Special case: 'config' has subcommands
+        if (site === 'config' && cursor === 2) {
+            return ['show', 'set', 'path'];
+        }
+        return [];
+    }
+    // cursor === 2 → completing the sub-command name under a site
+    if (cursor === 2) {
+        const subcommands = [];
+        for (const [, cmd] of getRegistry()) {
+            if (cmd.site === site) {
+                subcommands.push(cmd.name);
+                if (cmd.aliases?.length)
+                    subcommands.push(...cmd.aliases);
+            }
+        }
+        return [...new Set(subcommands)].sort();
+    }
+    // cursor >= 3 → no further completion
+    return [];
+}
+// ── Shell script generators ────────────────────────────────────────────────
+export function generateCompletion(shell) {
+    switch (shell) {
+        case 'bash':
+            return bashCompletionScript();
+        case 'zsh':
+            return zshCompletionScript();
+        case 'fish':
+            return fishCompletionScript();
+    }
+}
+function bashCompletionScript() {
+    return `# Bash completion for biocli
+# Add to ~/.bashrc:  eval "$(biocli completion bash)"
+_biocli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(biocli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _biocli_completions biocli
+`;
+}
+function zshCompletionScript() {
+    return `# Zsh completion for biocli
+# Add to ~/.zshrc:  eval "$(biocli completion zsh)"
+_biocli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(biocli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+compdef _biocli biocli
+`;
+}
+function fishCompletionScript() {
+    return `# Fish completion for biocli
+# Add to ~/.config/fish/config.fish:  biocli completion fish | source
+complete -c biocli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  biocli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`;
+}
+/**
+ * Print the completion script for the requested shell.
+ */
+export function printCompletionScript(shell) {
+    if (shell !== 'bash' && shell !== 'zsh' && shell !== 'fish') {
+        console.error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(generateCompletion(shell));
+}

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Configuration management for biocli.
+ *
+ * Reads and writes ~/.biocli/config.yaml for persistent settings
+ * such as API keys, email, and default output preferences.
+ *
+ * Priority for NCBI credentials:
+ *   1. Environment variables (NCBI_API_KEY, NCBI_EMAIL)
+ *   2. Config file (~/.biocli/config.yaml)
+ *
+ * Migration: if ~/.ncbicli/config.yaml exists and ~/.biocli/ does not,
+ * the old config is automatically migrated on first load.
+ */
+export interface BiocliConfig {
+    /** NCBI API key — get one at https://www.ncbi.nlm.nih.gov/account/settings/ */
+    api_key?: string;
+    /** Contact email (recommended by NCBI for E-utilities usage). */
+    email?: string;
+    /** Default settings applied when the user does not provide explicit flags. */
+    defaults?: {
+        /** Default output format (json, table, csv, etc.). */
+        format?: string;
+        /** Default maximum number of results to return. */
+        limit?: number;
+    };
+    /** Cache settings. */
+    cache?: {
+        /** Whether caching is enabled (default: true). */
+        enabled?: boolean;
+        /** Cache TTL in hours (default: 24). */
+        ttl?: number;
+    };
+}
+/** @deprecated Use BiocliConfig instead. */
+export type NcbiConfig = BiocliConfig;
+/**
+ * Load the config file from disk. Returns an empty object if the file
+ * does not exist or cannot be parsed.
+ */
+export declare function loadConfig(): BiocliConfig;
+/**
+ * Persist the given config object to ~/.biocli/config.yaml.
+ * Creates the directory if it does not exist.
+ */
+export declare function saveConfig(config: BiocliConfig): void;
+/** Return the absolute path to the config file. */
+export declare function getConfigPath(): string;
+/**
+ * Resolve the NCBI API key.
+ * Priority: env NCBI_API_KEY > config file api_key field.
+ */
+export declare function getApiKey(): string | undefined;
+/**
+ * Resolve the contact email.
+ * Priority: env NCBI_EMAIL > config file email field.
+ */
+export declare function getEmail(): string | undefined;

package/dist/config.js

@@ -0,0 +1,94 @@
+/**
+ * Configuration management for biocli.
+ *
+ * Reads and writes ~/.biocli/config.yaml for persistent settings
+ * such as API keys, email, and default output preferences.
+ *
+ * Priority for NCBI credentials:
+ *   1. Environment variables (NCBI_API_KEY, NCBI_EMAIL)
+ *   2. Config file (~/.biocli/config.yaml)
+ *
+ * Migration: if ~/.ncbicli/config.yaml exists and ~/.biocli/ does not,
+ * the old config is automatically migrated on first load.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, cpSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import yaml from 'js-yaml';
+// ── Paths ────────────────────────────────────────────────────────────────────
+const CONFIG_DIR = join(homedir(), '.biocli');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.yaml');
+const LEGACY_CONFIG_DIR = join(homedir(), '.ncbicli');
+const LEGACY_CONFIG_FILE = join(LEGACY_CONFIG_DIR, 'config.yaml');
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Migrate legacy ~/.ncbicli/config.yaml → ~/.biocli/config.yaml (one-time).
+ */
+function migrateIfNeeded() {
+    if (existsSync(CONFIG_DIR))
+        return; // already migrated or fresh install
+    if (!existsSync(LEGACY_CONFIG_FILE))
+        return; // nothing to migrate
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        cpSync(LEGACY_CONFIG_FILE, CONFIG_FILE);
+        console.error(`Migrated config: ${LEGACY_CONFIG_FILE} → ${CONFIG_FILE}`);
+    }
+    catch {
+        // Non-fatal — user can manually copy
+    }
+}
+/**
+ * Load the config file from disk. Returns an empty object if the file
+ * does not exist or cannot be parsed.
+ */
+export function loadConfig() {
+    migrateIfNeeded();
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        const parsed = yaml.load(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Persist the given config object to ~/.biocli/config.yaml.
+ * Creates the directory if it does not exist.
+ */
+export function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    const content = yaml.dump(config, {
+        indent: 2,
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: true,
+    });
+    writeFileSync(CONFIG_FILE, content, 'utf-8');
+}
+/** Return the absolute path to the config file. */
+export function getConfigPath() {
+    return CONFIG_FILE;
+}
+/**
+ * Resolve the NCBI API key.
+ * Priority: env NCBI_API_KEY > config file api_key field.
+ */
+export function getApiKey() {
+    return process.env.NCBI_API_KEY || loadConfig().api_key || undefined;
+}
+/**
+ * Resolve the contact email.
+ * Priority: env NCBI_EMAIL > config file email field.
+ */
+export function getEmail() {
+    return process.env.NCBI_EMAIL || loadConfig().email || undefined;
+}

package/dist/databases/enrichr.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Enrichr database backend for biocli.
+ *
+ * Enrichr API (https://maayanlab.cloud/Enrichr):
+ *   - No authentication required
+ *   - Rate limit: undocumented (we use 5/s conservatively)
+ *   - 2-step workflow: POST /addList → GET /enrich
+ *   - Response format: JSON
+ *
+ * Popular gene set libraries:
+ *   KEGG_2021_Human, GO_Biological_Process_2023, GO_Molecular_Function_2023,
+ *   GO_Cellular_Component_2023, WikiPathway_2023_Human, Reactome_2022,
+ *   MSigDB_Hallmark_2020, DisGeNET, OMIM_Disease, GWAS_Catalog_2023
+ */
+import { type DatabaseBackend } from './index.js';
+/**
+ * Submit a gene list to Enrichr and return the userListId.
+ * This is step 1 of the 2-step workflow.
+ *
+ * NOTE: Enrichr requires multipart/form-data (not URL-encoded).
+ */
+export declare function submitGeneList(genes: string[], description?: string): Promise<number>;
+/**
+ * Get enrichment results for a submitted gene list.
+ * This is step 2 of the 2-step workflow.
+ */
+export declare function getEnrichment(userListId: number, library: string): Promise<Record<string, unknown>[]>;
+export declare const enrichrBackend: DatabaseBackend;