@yangfei_93sky/biocli 0.2.0

package/dist/doctor.js

@@ -0,0 +1,151 @@
+/**
+ * biocli doctor — Diagnose configuration and backend connectivity.
+ *
+ * Checks Node.js version, config status, API key/email, and
+ * reachability of all 6 database backends in parallel.
+ */
+import chalk from 'chalk';
+import { loadConfig, getConfigPath, getApiKey, getEmail } from './config.js';
+import { getAllBackends } from './databases/index.js';
+import { getRegistry } from './registry.js';
+// ── Health-check endpoints per backend ───────────────────────────────────────
+const PING_ENDPOINTS = {
+    ncbi: 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi?retmode=json',
+    uniprot: 'https://rest.uniprot.org/uniprotkb/search?query=*&size=1&format=json',
+    kegg: 'https://rest.kegg.jp/info/kegg',
+    string: 'https://string-db.org/api/json/version',
+    ensembl: 'https://rest.ensembl.org/info/ping?content-type=application/json',
+    enrichr: 'https://maayanlab.cloud/Enrichr/datasetStatistics',
+};
+const PING_TIMEOUT = 5000;
+// ── Core checks ──────────────────────────────────────────────────────────────
+function checkNodeVersion() {
+    const version = process.version;
+    const major = Number(version.slice(1).split('.')[0]);
+    return {
+        name: 'Node.js',
+        value: version,
+        ok: major >= 20,
+        detail: major < 20 ? 'Requires Node.js >= 20' : undefined,
+    };
+}
+function checkConfig() {
+    const results = [];
+    const configPath = getConfigPath();
+    const config = loadConfig();
+    const hasConfig = Object.keys(config).length > 0;
+    results.push({
+        name: 'Config',
+        value: configPath,
+        ok: true,
+    });
+    const apiKey = getApiKey();
+    if (apiKey) {
+        const masked = apiKey.slice(0, 4) + '****' + apiKey.slice(-4);
+        results.push({
+            name: 'API key',
+            value: masked,
+            ok: true,
+            detail: '10 req/s',
+        });
+    }
+    else {
+        results.push({
+            name: 'API key',
+            value: 'not set',
+            ok: true,
+            detail: '3 req/s — optional (biocli config set api_key YOUR_KEY for 10 req/s)',
+        });
+    }
+    const email = getEmail();
+    results.push({
+        name: 'Email',
+        value: email ?? 'not set',
+        ok: true,
+        detail: email ? undefined : 'Optional — recommended for NCBI (biocli config set email YOUR_EMAIL)',
+    });
+    return results;
+}
+async function pingBackend(name, url) {
+    const start = Date.now();
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), PING_TIMEOUT);
+        const response = await fetch(url, { signal: controller.signal });
+        clearTimeout(timeout);
+        const elapsed = Date.now() - start;
+        // Consume and discard body so Node.js can close the connection promptly
+        await response.text().catch(() => { });
+        if (response.ok) {
+            return { name, value: url.split('/').slice(0, 3).join('/'), ok: true, detail: `${elapsed}ms` };
+        }
+        return { name, value: url.split('/').slice(0, 3).join('/'), ok: false, detail: `HTTP ${response.status} (${elapsed}ms)` };
+    }
+    catch (err) {
+        const elapsed = Date.now() - start;
+        const msg = err instanceof Error && err.name === 'AbortError'
+            ? `timeout (${PING_TIMEOUT}ms)`
+            : err instanceof Error ? err.message : String(err);
+        return { name, value: url.split('/').slice(0, 3).join('/'), ok: false, detail: msg };
+    }
+}
+function checkCommands() {
+    const count = getRegistry().size;
+    return { name: 'Commands', value: `${count} registered`, ok: count > 0 };
+}
+// ── Main runner ──────────────────────────────────────────────────────────────
+export async function runDoctor() {
+    const checks = [];
+    // System checks
+    checks.push(checkNodeVersion());
+    checks.push(...checkConfig());
+    // Backend connectivity (parallel)
+    const backends = getAllBackends();
+    const pingPromises = backends.map(b => {
+        const url = PING_ENDPOINTS[b.id] ?? `${b.baseUrl}`;
+        return pingBackend(b.name, url);
+    });
+    const pingResults = await Promise.allSettled(pingPromises);
+    for (const result of pingResults) {
+        if (result.status === 'fulfilled') {
+            checks.push(result.value);
+        }
+    }
+    // Command registry
+    checks.push(checkCommands());
+    const allPassed = checks.every(c => c.ok);
+    return { checks, allPassed };
+}
+// ── Formatters ───────────────────────────────────────────────────────────────
+export function formatDoctorText(checks, allPassed) {
+    const lines = ['', chalk.bold('biocli doctor'), ''];
+    for (const check of checks) {
+        const status = check.ok ? chalk.green('OK') : chalk.red('FAIL');
+        const detail = check.detail ? chalk.dim(` (${check.detail})`) : '';
+        const name = check.name.padEnd(14);
+        const value = check.value;
+        lines.push(`  ${name} ${value.padEnd(44)} ${status}${detail}`);
+    }
+    const passedCount = checks.filter(c => c.ok).length;
+    const failedCount = checks.length - passedCount;
+    lines.push('');
+    if (allPassed) {
+        lines.push(chalk.green(`  All ${checks.length} checks passed.`));
+    }
+    else {
+        lines.push(chalk.yellow(`  ${passedCount} passed, ${failedCount} failed.`));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatDoctorJson(checks, allPassed) {
+    return JSON.stringify({
+        allPassed,
+        checks: checks.map(c => ({
+            name: c.name,
+            value: c.value,
+            ok: c.ok,
+            ...(c.detail ? { detail: c.detail } : {}),
+        })),
+    }, null, 2);
+}

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Unified error types for biocli.
+ *
+ * All errors thrown by the framework should extend CliError so that
+ * the top-level handler can render consistent, helpful output with
+ * emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * biocli follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (AdapterLoadError)
+ *  75   Temporary failure, retry later  (TimeoutError, RateLimitError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C
+ */
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERIC_ERROR: 1;
+    readonly USAGE_ERROR: 2;
+    readonly EMPTY_RESULT: 66;
+    readonly SERVICE_UNAVAIL: 69;
+    readonly TEMPFAIL: 75;
+    readonly CONFIG_ERROR: 78;
+    readonly INTERRUPTED: 130;
+};
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+export declare class CliError extends Error {
+    /** Machine-readable error code (e.g. 'API_ERROR', 'RATE_LIMITED') */
+    readonly code: string;
+    /** Human-readable hint on how to fix the problem */
+    readonly hint?: string;
+    /** Unix process exit code — defaults to 1 (generic error) */
+    readonly exitCode: ExitCode;
+    constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
+}
+export declare class CommandExecutionError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class ConfigError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class TimeoutError extends CliError {
+    constructor(label: string, seconds: number, hint?: string);
+}
+export declare class ArgumentError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class EmptyResultError extends CliError {
+    constructor(command: string, hint?: string);
+}
+export declare class AdapterLoadError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class RateLimitError extends CliError {
+    constructor(message?: string, hint?: string);
+}
+export declare class ApiError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/** Extract a human-readable message from an unknown caught value. */
+export declare function getErrorMessage(error: unknown): string;
+/** Error code -> emoji mapping for CLI output rendering. */
+export declare const ERROR_ICONS: Record<string, string>;

package/dist/errors.js

@@ -0,0 +1,105 @@
+/**
+ * Unified error types for biocli.
+ *
+ * All errors thrown by the framework should extend CliError so that
+ * the top-level handler can render consistent, helpful output with
+ * emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * biocli follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (AdapterLoadError)
+ *  75   Temporary failure, retry later  (TimeoutError, RateLimitError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C
+ */
+// ── Exit code table ──────────────────────────────────────────────────────────
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    GENERIC_ERROR: 1,
+    USAGE_ERROR: 2, // Bad arguments / command misuse
+    EMPTY_RESULT: 66, // No data / not found           (EX_NOINPUT)
+    SERVICE_UNAVAIL: 69, // Adapter load failure           (EX_UNAVAILABLE)
+    TEMPFAIL: 75, // Timeout / rate limit           (EX_TEMPFAIL)
+    CONFIG_ERROR: 78, // Missing / invalid config       (EX_CONFIG)
+    INTERRUPTED: 130, // Ctrl-C / SIGINT
+};
+// ── Base class ───────────────────────────────────────────────────────────────
+export class CliError extends Error {
+    /** Machine-readable error code (e.g. 'API_ERROR', 'RATE_LIMITED') */
+    code;
+    /** Human-readable hint on how to fix the problem */
+    hint;
+    /** Unix process exit code — defaults to 1 (generic error) */
+    exitCode;
+    constructor(code, message, hint, exitCode = EXIT_CODES.GENERIC_ERROR) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+    }
+}
+// ── Typed subclasses ─────────────────────────────────────────────────────────
+export class CommandExecutionError extends CliError {
+    constructor(message, hint) {
+        super('COMMAND_EXEC', message, hint, EXIT_CODES.GENERIC_ERROR);
+    }
+}
+export class ConfigError extends CliError {
+    constructor(message, hint) {
+        super('CONFIG', message, hint, EXIT_CODES.CONFIG_ERROR);
+    }
+}
+export class TimeoutError extends CliError {
+    constructor(label, seconds, hint) {
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again later, or increase the timeout if the NCBI server is slow', EXIT_CODES.TEMPFAIL);
+    }
+}
+export class ArgumentError extends CliError {
+    constructor(message, hint) {
+        super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
+    }
+}
+export class EmptyResultError extends CliError {
+    constructor(command, hint) {
+        super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'Check your query parameters or try a different search term', EXIT_CODES.EMPTY_RESULT);
+    }
+}
+export class AdapterLoadError extends CliError {
+    constructor(message, hint) {
+        super('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+    }
+}
+export class RateLimitError extends CliError {
+    constructor(message, hint) {
+        super('RATE_LIMITED', message ?? 'NCBI API rate limit exceeded', hint ?? 'Add an API key (biocli config set api_key YOUR_KEY) to increase the rate limit from 3 to 10 requests/sec', EXIT_CODES.TEMPFAIL);
+    }
+}
+export class ApiError extends CliError {
+    constructor(message, hint) {
+        super('API_ERROR', message, hint ?? 'Check the NCBI API status at https://www.ncbi.nlm.nih.gov/home/develop/', EXIT_CODES.GENERIC_ERROR);
+    }
+}
+// ── Utilities ────────────────────────────────────────────────────────────────
+/** Extract a human-readable message from an unknown caught value. */
+export function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Error code -> emoji mapping for CLI output rendering. */
+export const ERROR_ICONS = {
+    TIMEOUT: '⏱ ',
+    ARGUMENT: '❌',
+    EMPTY_RESULT: '📭',
+    COMMAND_EXEC: '💥',
+    ADAPTER_LOAD: '📦',
+    NETWORK: '🌐',
+    API_ERROR: '🚫',
+    RATE_LIMITED: '⏳',
+    CONFIG: '⚙️ ',
+};

package/dist/execution.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Command execution: validates args, creates HttpContext, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. HttpContext creation (replaces browser sessions from opencli)
+ * 3. Timeout enforcement
+ * 4. Lazy-loading of TS modules from manifest
+ * 5. Lifecycle hooks (onBeforeExecute / onAfterExecute)
+ */
+import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
+export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
+export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean, opts?: {
+    noCache?: boolean;
+}): Promise<unknown>;

package/dist/execution.js

@@ -0,0 +1,178 @@
+/**
+ * Command execution: validates args, creates HttpContext, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. HttpContext creation (replaces browser sessions from opencli)
+ * 3. Timeout enforcement
+ * 4. Lazy-loading of TS modules from manifest
+ * 5. Lifecycle hooks (onBeforeExecute / onAfterExecute)
+ */
+import { getRegistry, fullName, } from './registry.js';
+import { pathToFileURL } from 'node:url';
+import { executePipeline } from './pipeline/index.js';
+import { AdapterLoadError, ArgumentError, CommandExecutionError, TimeoutError, getErrorMessage, } from './errors.js';
+import { emitHook } from './hooks.js';
+import { createHttpContextForDatabase } from './databases/index.js';
+import { buildCacheKey, getCached, setCached } from './cache.js';
+import { loadConfig } from './config.js';
+/** Default command timeout in seconds (used when timeoutSeconds is set). */
+const DEFAULT_COMMAND_TIMEOUT = 60;
+const _loadedModules = new Set();
+// ── Argument coercion & validation ──────────────────────────────────────────
+export function coerceAndValidateArgs(cmdArgs, kwargs) {
+    const result = { ...kwargs };
+    for (const argDef of cmdArgs) {
+        const val = result[argDef.name];
+        if (argDef.required && (val === undefined || val === null || val === '')) {
+            throw new ArgumentError(`Argument "${argDef.name}" is required.`, argDef.help ?? `Provide a value for --${argDef.name}`);
+        }
+        if (val !== undefined && val !== null) {
+            if (argDef.type === 'int' || argDef.type === 'number') {
+                const num = Number(val);
+                if (Number.isNaN(num)) {
+                    throw new ArgumentError(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+                }
+                result[argDef.name] = num;
+            }
+            else if (argDef.type === 'boolean' || argDef.type === 'bool') {
+                if (typeof val === 'string') {
+                    const lower = val.toLowerCase();
+                    if (lower === 'true' || lower === '1')
+                        result[argDef.name] = true;
+                    else if (lower === 'false' || lower === '0')
+                        result[argDef.name] = false;
+                    else
+                        throw new ArgumentError(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+                }
+                else {
+                    result[argDef.name] = Boolean(val);
+                }
+            }
+            const coercedVal = result[argDef.name];
+            if (argDef.choices && argDef.choices.length > 0) {
+                if (!argDef.choices.map(String).includes(String(coercedVal))) {
+                    throw new ArgumentError(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+                }
+            }
+        }
+        else if (argDef.default !== undefined) {
+            result[argDef.name] = argDef.default;
+        }
+    }
+    return result;
+}
+// ── Command runner ──────────────────────────────────────────────────────────
+async function runCommand(cmd, ctx, kwargs, debug) {
+    const internal = cmd;
+    if (internal._lazy && internal._modulePath) {
+        const modulePath = internal._modulePath;
+        if (!_loadedModules.has(modulePath)) {
+            try {
+                await import(pathToFileURL(modulePath).href);
+                _loadedModules.add(modulePath);
+            }
+            catch (err) {
+                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
+            }
+        }
+        const updated = getRegistry().get(fullName(cmd));
+        if (updated?.func) {
+            return updated.func(ctx, kwargs, debug);
+        }
+        if (updated?.pipeline) {
+            return executePipeline(updated.pipeline, ctx, kwargs);
+        }
+    }
+    if (cmd.func)
+        return cmd.func(ctx, kwargs, debug);
+    if (cmd.pipeline)
+        return executePipeline(cmd.pipeline, ctx, kwargs);
+    throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
+}
+// ── Timeout helper ──────────────────────────────────────────────────────────
+async function runWithTimeout(promise, timeoutSeconds, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError(label, timeoutSeconds)), timeoutSeconds * 1000);
+        promise
+            .then((val) => { clearTimeout(timer); resolve(val); })
+            .catch((err) => { clearTimeout(timer); reject(err); });
+    });
+}
+// ── Required env check ──────────────────────────────────────────────────────
+function ensureRequiredEnv(cmd) {
+    const missing = (cmd.requiredEnv ?? []).find(({ name }) => {
+        const value = process.env[name];
+        return value === undefined || value === null || value === '';
+    });
+    if (!missing)
+        return;
+    throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
+}
+// ── Main entry point ────────────────────────────────────────────────────────
+export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
+    let kwargs;
+    try {
+        kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+    }
+    catch (err) {
+        if (err instanceof ArgumentError)
+            throw err;
+        throw new ArgumentError(getErrorMessage(err));
+    }
+    ensureRequiredEnv(cmd);
+    const hookCtx = {
+        command: fullName(cmd),
+        args: kwargs,
+        startedAt: Date.now(),
+    };
+    await emitHook('onBeforeExecute', hookCtx);
+    // ── Cache check ───────────────────────────────────────────────────────
+    const databaseId = cmd.database ?? 'ncbi';
+    const cacheKey = buildCacheKey(databaseId, fullName(cmd), kwargs);
+    const cacheConfig = loadConfig().cache;
+    const cacheEnabled = (cacheConfig?.enabled ?? true) && !opts.noCache;
+    const cacheTtlMs = (cacheConfig?.ttl ?? 24) * 60 * 60 * 1000;
+    if (cacheEnabled && databaseId !== 'aggregate') {
+        const cached = getCached(databaseId, fullName(cmd), cacheKey, cacheTtlMs);
+        if (cached !== null) {
+            if (debug)
+                console.error(`[Cache] HIT ${cacheKey}`);
+            hookCtx.finishedAt = Date.now();
+            await emitHook('onAfterExecute', hookCtx, cached);
+            return cached;
+        }
+        if (debug)
+            console.error(`[Cache] MISS ${cacheKey}`);
+    }
+    let result;
+    try {
+        // Aggregate commands create their own multi-database contexts internally
+        const ctx = databaseId === 'aggregate'
+            ? { databaseId: 'aggregate', fetch: async () => { throw new Error('use createHttpContextForDatabase()'); }, fetchJson: async () => { throw new Error('use createHttpContextForDatabase()'); }, fetchXml: async () => { throw new Error('use createHttpContextForDatabase()'); }, fetchText: async () => { throw new Error('use createHttpContextForDatabase()'); } }
+            : createHttpContextForDatabase(databaseId);
+        const timeout = cmd.timeoutSeconds;
+        if (timeout !== undefined && timeout > 0) {
+            result = await runWithTimeout(runCommand(cmd, ctx, kwargs, debug), timeout, fullName(cmd));
+        }
+        else {
+            result = await runCommand(cmd, ctx, kwargs, debug);
+        }
+    }
+    catch (err) {
+        hookCtx.error = err;
+        hookCtx.finishedAt = Date.now();
+        await emitHook('onAfterExecute', hookCtx);
+        throw err;
+    }
+    // ── Cache store ──────────────────────────────────────────────────────
+    if (cacheEnabled && databaseId !== 'aggregate' && result !== null && result !== undefined) {
+        try {
+            setCached(databaseId, fullName(cmd), cacheKey, result, cacheTtlMs);
+        }
+        catch { /* non-fatal */ }
+    }
+    hookCtx.finishedAt = Date.now();
+    await emitHook('onAfterExecute', hookCtx, result);
+    return result;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into biocli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+export type HookName = 'onStartup' | 'onBeforeExecute' | 'onAfterExecute';
+export interface HookContext {
+    /** Command full name in "site/name" format, or "__startup__" for onStartup */
+    command: string;
+    /** Coerced and validated arguments */
+    args: Record<string, unknown>;
+    /** Epoch ms when execution started (set by executeCommand) */
+    startedAt?: number;
+    /** Epoch ms when execution finished (set by executeCommand) */
+    finishedAt?: number;
+    /** Error thrown by the command, if execution failed */
+    error?: unknown;
+    /** Plugins can attach arbitrary data here for cross-hook communication */
+    [key: string]: unknown;
+}
+export type HookFn = (ctx: HookContext, result?: unknown) => void | Promise<void>;
+declare global {
+    var __biocli_hooks__: Map<HookName, HookFn[]> | undefined;
+    /** @deprecated Alias for __biocli_hooks__. */
+    var __ncbicli_hooks__: Map<HookName, HookFn[]> | undefined;
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export declare function onStartup(fn: HookFn): void;
+/** Register a hook that fires before every command execution. */
+export declare function onBeforeExecute(fn: HookFn): void;
+/** Register a hook that fires after every command execution with the result. */
+export declare function onAfterExecute(fn: HookFn): void;
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export declare function emitHook(name: HookName, ctx: HookContext, result?: unknown): Promise<void>;
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export declare function clearAllHooks(): void;

package/dist/hooks.js

@@ -0,0 +1,58 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into biocli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+const _hooks = globalThis.__biocli_hooks__ ??= globalThis.__ncbicli_hooks__ ?? new Map();
+globalThis.__ncbicli_hooks__ = _hooks;
+// ── Registration API (used by plugins) ─────────────────────────────────────
+function addHook(name, fn) {
+    const list = _hooks.get(name) ?? [];
+    if (list.includes(fn))
+        return;
+    list.push(fn);
+    _hooks.set(name, list);
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export function onStartup(fn) {
+    addHook('onStartup', fn);
+}
+/** Register a hook that fires before every command execution. */
+export function onBeforeExecute(fn) {
+    addHook('onBeforeExecute', fn);
+}
+/** Register a hook that fires after every command execution with the result. */
+export function onAfterExecute(fn) {
+    addHook('onAfterExecute', fn);
+}
+// ── Emit API (used internally by biocli core) ──────────────────────────────
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export async function emitHook(name, ctx, result) {
+    const handlers = _hooks.get(name);
+    if (!handlers || handlers.length === 0)
+        return;
+    for (const fn of handlers) {
+        try {
+            await fn(ctx, result);
+        }
+        catch (err) {
+            console.error(`[biocli] Hook ${name} handler failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export function clearAllHooks() {
+    _hooks.clear();
+}

package/dist/main.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * biocli entry point.
+ *
+ * Discovers built-in and user CLI definitions, loads plugins,
+ * fires the onStartup hook, then hands off to Commander.
+ */
+import './databases/ncbi.js';
+import './databases/uniprot.js';
+import './databases/kegg.js';
+import './databases/string-db.js';
+import './databases/ensembl.js';
+import './databases/enrichr.js';

package/dist/main.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * biocli entry point.
+ *
+ * Discovers built-in and user CLI definitions, loads plugins,
+ * fires the onStartup hook, then hands off to Commander.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { discoverClis, discoverPlugins } from './discovery.js';
+import { runCli } from './cli.js';
+import { emitHook } from './hooks.js';
+// Register database backends (side-effect imports)
+import './databases/ncbi.js';
+import './databases/uniprot.js';
+import './databases/kegg.js';
+import './databases/string-db.js';
+import './databases/ensembl.js';
+import './databases/enrichr.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUILTIN_CLIS = join(__dirname, 'clis');
+async function main() {
+    await discoverClis(BUILTIN_CLIS);
+    await discoverPlugins();
+    await emitHook('onStartup', { command: '__startup__', args: {} });
+    runCli();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});