@yangfei_93sky/biocli 0.2.0

package/dist/rate-limiter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sliding-window rate limiter for biocli database backends.
+ *
+ * Each database has its own rate limit:
+ *   - NCBI:    3/s (anonymous), 10/s (with API key)
+ *   - UniProt: 50/s
+ *   - KEGG:    10/s
+ *   - STRING:  1/s
+ *   - Ensembl: 15/s
+ *   - Enrichr: 5/s
+ *
+ * Singletons are maintained via globalThis so that all code paths
+ * share the same limiter instances (including across npm-linked plugins).
+ */
+export declare class RateLimiter {
+    private maxPerSecond;
+    /** Timestamps (ms) of requests within the current 1-second window. */
+    private timestamps;
+    /** Queued resolve callbacks waiting for a slot. */
+    private queue;
+    /** Whether a drain loop is already scheduled. */
+    private draining;
+    constructor(maxPerSecond: number);
+    /**
+     * Wait until a request slot is available, then record the timestamp.
+     * Callers should `await limiter.acquire()` before each HTTP request.
+     */
+    acquire(): Promise<void>;
+    /** Update the rate limit (e.g. when an API key is added mid-session). */
+    setRate(maxPerSecond: number): void;
+    /** Remove timestamps older than 1 second from the window. */
+    private pruneOldTimestamps;
+    /** Start a drain loop that services the queue as slots open up. */
+    private scheduleDrain;
+}
+declare global {
+    var __biocli_rate_limiters__: Map<string, RateLimiter> | undefined;
+    var __ncbicli_rate_limiter__: RateLimiter | undefined;
+    var __ncbicli_rate_limiter_has_key__: boolean | undefined;
+}
+/**
+ * Get (or create) a rate limiter for a specific database.
+ *
+ * Each database gets its own independent limiter instance keyed by ID.
+ */
+export declare function getRateLimiterForDatabase(databaseId: string, maxPerSecond: number): RateLimiter;
+/**
+ * Get (or create) the NCBI rate limiter.
+ *
+ * @deprecated Use getRateLimiterForDatabase('ncbi', rate) instead.
+ *             Kept for backward compatibility with existing NCBI adapters.
+ *
+ * @param hasApiKey  Whether the user has an NCBI API key configured.
+ *                   This determines the rate: 10/s with key, 3/s without.
+ */
+export declare function getRateLimiter(hasApiKey: boolean): RateLimiter;

package/dist/rate-limiter.js

@@ -0,0 +1,120 @@
+/**
+ * Sliding-window rate limiter for biocli database backends.
+ *
+ * Each database has its own rate limit:
+ *   - NCBI:    3/s (anonymous), 10/s (with API key)
+ *   - UniProt: 50/s
+ *   - KEGG:    10/s
+ *   - STRING:  1/s
+ *   - Ensembl: 15/s
+ *   - Enrichr: 5/s
+ *
+ * Singletons are maintained via globalThis so that all code paths
+ * share the same limiter instances (including across npm-linked plugins).
+ */
+import { sleep } from './utils.js';
+// ── RateLimiter class ────────────────────────────────────────────────────────
+export class RateLimiter {
+    maxPerSecond;
+    /** Timestamps (ms) of requests within the current 1-second window. */
+    timestamps = [];
+    /** Queued resolve callbacks waiting for a slot. */
+    queue = [];
+    /** Whether a drain loop is already scheduled. */
+    draining = false;
+    constructor(maxPerSecond) {
+        this.maxPerSecond = maxPerSecond;
+    }
+    /**
+     * Wait until a request slot is available, then record the timestamp.
+     * Callers should `await limiter.acquire()` before each HTTP request.
+     */
+    async acquire() {
+        this.pruneOldTimestamps();
+        if (this.timestamps.length < this.maxPerSecond) {
+            // Slot available immediately
+            this.timestamps.push(Date.now());
+            return;
+        }
+        // No slot available — enqueue and wait
+        return new Promise((resolve) => {
+            this.queue.push(resolve);
+            this.scheduleDrain();
+        });
+    }
+    /** Update the rate limit (e.g. when an API key is added mid-session). */
+    setRate(maxPerSecond) {
+        this.maxPerSecond = maxPerSecond;
+    }
+    // ── Internal helpers ────────────────────────────────────────────────────
+    /** Remove timestamps older than 1 second from the window. */
+    pruneOldTimestamps() {
+        const cutoff = Date.now() - 1000;
+        while (this.timestamps.length > 0 && this.timestamps[0] <= cutoff) {
+            this.timestamps.shift();
+        }
+    }
+    /** Start a drain loop that services the queue as slots open up. */
+    scheduleDrain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        const drain = async () => {
+            while (this.queue.length > 0) {
+                this.pruneOldTimestamps();
+                if (this.timestamps.length < this.maxPerSecond) {
+                    // A slot opened up — release the next waiter
+                    this.timestamps.push(Date.now());
+                    const next = this.queue.shift();
+                    if (next)
+                        next();
+                }
+                else {
+                    // Calculate how long until the oldest timestamp expires
+                    const oldest = this.timestamps[0];
+                    const waitMs = Math.max(1, (oldest + 1000) - Date.now() + 1);
+                    await sleep(waitMs);
+                }
+            }
+            this.draining = false;
+        };
+        // Fire-and-forget — errors here are programming bugs, not user-facing
+        drain().catch(() => { this.draining = false; });
+    }
+}
+const _limiters = globalThis.__biocli_rate_limiters__ ??= new Map();
+/**
+ * Get (or create) a rate limiter for a specific database.
+ *
+ * Each database gets its own independent limiter instance keyed by ID.
+ */
+export function getRateLimiterForDatabase(databaseId, maxPerSecond) {
+    let limiter = _limiters.get(databaseId);
+    if (!limiter) {
+        limiter = new RateLimiter(maxPerSecond);
+        _limiters.set(databaseId, limiter);
+    }
+    return limiter;
+}
+/**
+ * Get (or create) the NCBI rate limiter.
+ *
+ * @deprecated Use getRateLimiterForDatabase('ncbi', rate) instead.
+ *             Kept for backward compatibility with existing NCBI adapters.
+ *
+ * @param hasApiKey  Whether the user has an NCBI API key configured.
+ *                   This determines the rate: 10/s with key, 3/s without.
+ */
+export function getRateLimiter(hasApiKey) {
+    const rate = hasApiKey ? 10 : 3;
+    // Delegate to the per-database registry
+    const limiter = getRateLimiterForDatabase('ncbi', rate);
+    // If the API key status changed, update the rate
+    if (globalThis.__ncbicli_rate_limiter_has_key__ !== hasApiKey) {
+        limiter.setRate(rate);
+        globalThis.__ncbicli_rate_limiter_has_key__ = hasApiKey;
+    }
+    // Keep legacy global reference in sync
+    globalThis.__ncbicli_rate_limiter__ = limiter;
+    return limiter;
+}

package/dist/registry-api.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @experimental This API is pre-v1.0 and may change without notice.
+ * See PLUGIN_DEV.md and docs/decisions/001-plugin-ecosystem.md.
+ *
+ * Public API re-exports for plugin authors and external consumers.
+ *
+ * Import from '@biocli/cli/registry' to register commands:
+ *
+ * ```ts
+ * import { cli, Strategy } from '@biocli/cli/registry';
+ * ```
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs } from './registry.js';
+export type { HttpContext, NcbiFetchOptions } from './types.js';

package/dist/registry-api.js

@@ -0,0 +1,13 @@
+/**
+ * @experimental This API is pre-v1.0 and may change without notice.
+ * See PLUGIN_DEV.md and docs/decisions/001-plugin-ecosystem.md.
+ *
+ * Public API re-exports for plugin authors and external consumers.
+ *
+ * Import from '@biocli/cli/registry' to register commands:
+ *
+ * ```ts
+ * import { cli, Strategy } from '@biocli/cli/registry';
+ * ```
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';

package/dist/registry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ *
+ * Adapted from opencli's registry.ts for NCBI public API access only.
+ * No browser, no cookie/header/intercept/UI strategies — just PUBLIC and API_KEY.
+ */
+import type { HttpContext } from './types.js';
+export declare enum Strategy {
+    /** No authentication needed — anonymous NCBI E-utilities access. */
+    PUBLIC = "public",
+    /** Requires an NCBI API key for higher rate limits or restricted endpoints. */
+    API_KEY = "api_key"
+}
+export interface Arg {
+    name: string;
+    type?: string;
+    default?: unknown;
+    required?: boolean;
+    positional?: boolean;
+    help?: string;
+    choices?: string[];
+}
+export interface RequiredEnv {
+    name: string;
+    help?: string;
+}
+export type CommandArgs = Record<string, any>;
+export interface CliCommand {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    /** NCBI database this command targets (e.g. 'pubmed', 'gene', 'geo'). */
+    database?: string;
+    strategy?: Strategy;
+    args: Arg[];
+    columns?: string[];
+    func?: (ctx: HttpContext, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
+    pipeline?: Record<string, unknown>[];
+    timeoutSeconds?: number;
+    /** Origin of this command: 'yaml', 'ts', or plugin name. */
+    source?: string;
+    requiredEnv?: RequiredEnv[];
+    /** Deprecation note shown in help / execution warnings. */
+    deprecated?: boolean | string;
+    /** Preferred replacement command, if any. */
+    replacedBy?: string;
+    /** Override the default CLI output format when the user does not pass -f/--format. */
+    defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
+}
+/** Internal extension for lazy-loaded TS modules (not exposed in public API). */
+export interface InternalCliCommand extends CliCommand {
+    _lazy?: boolean;
+    _modulePath?: string;
+}
+export interface CliOptions extends Partial<Omit<CliCommand, 'args' | 'description'>> {
+    site: string;
+    name: string;
+    description?: string;
+    args?: Arg[];
+}
+declare global {
+    var __biocli_registry__: Map<string, CliCommand> | undefined;
+    /** @deprecated Alias for __biocli_registry__ — kept for plugin backward compat. */
+    var __ncbicli_registry__: Map<string, CliCommand> | undefined;
+}
+/**
+ * Register a new CLI command. Returns the created CliCommand object.
+ *
+ * ```ts
+ * export const search = cli({
+ *   site: 'pubmed',
+ *   name: 'search',
+ *   description: 'Search PubMed articles',
+ *   database: 'pubmed',
+ *   args: [{ name: 'query', positional: true, required: true, help: 'Search query' }],
+ *   func: async (ctx, kwargs) => { ... },
+ * });
+ * ```
+ */
+export declare function cli(opts: CliOptions): CliCommand;
+/** Return the global command registry map. */
+export declare function getRegistry(): Map<string, CliCommand>;
+/** Return the canonical key for a command: "site/name". */
+export declare function fullName(cmd: CliCommand): string;
+/** Return a human-readable label for the command's access strategy. */
+export declare function strategyLabel(cmd: CliCommand): string;
+/** Add a command (and its aliases) to the global registry. */
+export declare function registerCommand(cmd: CliCommand): void;
+export declare function normalizeAliases(aliases: string[] | undefined, commandName: string): string[];

package/dist/registry.js

@@ -0,0 +1,100 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ *
+ * Adapted from opencli's registry.ts for NCBI public API access only.
+ * No browser, no cookie/header/intercept/UI strategies — just PUBLIC and API_KEY.
+ */
+// ── Strategy ─────────────────────────────────────────────────────────────────
+export var Strategy;
+(function (Strategy) {
+    /** No authentication needed — anonymous NCBI E-utilities access. */
+    Strategy["PUBLIC"] = "public";
+    /** Requires an NCBI API key for higher rate limits or restricted endpoints. */
+    Strategy["API_KEY"] = "api_key";
+})(Strategy || (Strategy = {}));
+const _registry = globalThis.__biocli_registry__ ??= globalThis.__ncbicli_registry__ ?? new Map();
+// Keep legacy alias in sync
+globalThis.__ncbicli_registry__ = _registry;
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Register a new CLI command. Returns the created CliCommand object.
+ *
+ * ```ts
+ * export const search = cli({
+ *   site: 'pubmed',
+ *   name: 'search',
+ *   description: 'Search PubMed articles',
+ *   database: 'pubmed',
+ *   args: [{ name: 'query', positional: true, required: true, help: 'Search query' }],
+ *   func: async (ctx, kwargs) => { ... },
+ * });
+ * ```
+ */
+export function cli(opts) {
+    const strategy = opts.strategy ?? Strategy.PUBLIC;
+    const aliases = normalizeAliases(opts.aliases, opts.name);
+    const cmd = {
+        site: opts.site,
+        name: opts.name,
+        aliases,
+        description: opts.description ?? '',
+        database: opts.database,
+        strategy,
+        args: opts.args ?? [],
+        columns: opts.columns,
+        func: opts.func,
+        pipeline: opts.pipeline,
+        timeoutSeconds: opts.timeoutSeconds,
+        requiredEnv: opts.requiredEnv,
+        deprecated: opts.deprecated,
+        replacedBy: opts.replacedBy,
+        defaultFormat: opts.defaultFormat,
+    };
+    registerCommand(cmd);
+    return cmd;
+}
+/** Return the global command registry map. */
+export function getRegistry() {
+    return _registry;
+}
+/** Return the canonical key for a command: "site/name". */
+export function fullName(cmd) {
+    return `${cmd.site}/${cmd.name}`;
+}
+/** Return a human-readable label for the command's access strategy. */
+export function strategyLabel(cmd) {
+    return cmd.strategy ?? Strategy.PUBLIC;
+}
+/** Add a command (and its aliases) to the global registry. */
+export function registerCommand(cmd) {
+    const canonicalKey = fullName(cmd);
+    const existing = _registry.get(canonicalKey);
+    if (existing) {
+        // Remove stale alias entries that pointed to the old command object
+        for (const [key, value] of _registry.entries()) {
+            if (value === existing && key !== canonicalKey)
+                _registry.delete(key);
+        }
+    }
+    const aliases = normalizeAliases(cmd.aliases, cmd.name);
+    cmd.aliases = aliases.length > 0 ? aliases : undefined;
+    _registry.set(canonicalKey, cmd);
+    for (const alias of aliases) {
+        _registry.set(`${cmd.site}/${alias}`, cmd);
+    }
+}
+// ── Internal helpers ────────────────────────────────────────────────────────
+export function normalizeAliases(aliases, commandName) {
+    if (!Array.isArray(aliases) || aliases.length === 0)
+        return [];
+    const seen = new Set();
+    const normalized = [];
+    for (const alias of aliases) {
+        const value = typeof alias === 'string' ? alias.trim() : '';
+        if (!value || value === commandName || seen.has(value))
+            continue;
+        seen.add(value);
+        normalized.push(value);
+    }
+    return normalized;
+}

package/dist/schema.d.ts

@@ -0,0 +1,80 @@
+/**
+ * JSON Schema definitions for biocli result types.
+ *
+ * Used by the `biocli schema` command to help AI agents validate outputs.
+ */
+export declare const biocliResultSchema: {
+    $schema: string;
+    title: string;
+    description: string;
+    type: string;
+    properties: {
+        data: {
+            description: string;
+        };
+        ids: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+            };
+        };
+        sources: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+            };
+        };
+        warnings: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+            };
+        };
+        queriedAt: {
+            type: string;
+            format: string;
+            description: string;
+        };
+        organism: {
+            type: string;
+            description: string;
+        };
+        query: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const resultWithMetaSchema: {
+    $schema: string;
+    title: string;
+    description: string;
+    type: string;
+    properties: {
+        rows: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+            };
+        };
+        meta: {
+            type: string;
+            properties: {
+                totalCount: {
+                    type: string;
+                    description: string;
+                };
+                query: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+    };
+    required: string[];
+};

package/dist/schema.js

@@ -0,0 +1,72 @@
+/**
+ * JSON Schema definitions for biocli result types.
+ *
+ * Used by the `biocli schema` command to help AI agents validate outputs.
+ */
+export const biocliResultSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'BiocliResult',
+    description: 'Structured result envelope returned by biocli aggregation commands (gene-profile, gene-dossier, etc.)',
+    type: 'object',
+    properties: {
+        data: {
+            description: 'Primary result payload (structure varies by command)',
+        },
+        ids: {
+            type: 'object',
+            description: 'Cross-database identifiers (e.g. geneId, uniprotAccession, ensemblId)',
+            additionalProperties: { type: 'string' },
+        },
+        sources: {
+            type: 'array',
+            description: 'Database backends that contributed to this result',
+            items: { type: 'string' },
+        },
+        warnings: {
+            type: 'array',
+            description: 'Non-fatal issues encountered during data retrieval',
+            items: { type: 'string' },
+        },
+        queriedAt: {
+            type: 'string',
+            format: 'date-time',
+            description: 'ISO 8601 timestamp of when the query was executed',
+        },
+        organism: {
+            type: 'string',
+            description: 'Scientific name of the organism (if applicable)',
+        },
+        query: {
+            type: 'string',
+            description: 'Original query string',
+        },
+    },
+    required: ['data', 'ids', 'sources', 'warnings', 'queriedAt', 'query'],
+};
+export const resultWithMetaSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'ResultWithMeta',
+    description: 'Result envelope returned by atomic biocli commands (search, fetch, etc.)',
+    type: 'object',
+    properties: {
+        rows: {
+            type: 'array',
+            description: 'Array of result records (columns vary by command)',
+            items: { type: 'object' },
+        },
+        meta: {
+            type: 'object',
+            properties: {
+                totalCount: {
+                    type: 'number',
+                    description: 'Total number of results available (may exceed returned rows)',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Original query string',
+                },
+            },
+        },
+    },
+    required: ['rows'],
+};

package/dist/spinner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lightweight terminal spinner — zero dependencies.
+ *
+ * Shows a cycling animation (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) with an optional message
+ * while async work is in progress. Clears itself when stopped.
+ */
+export interface Spinner {
+    /** Update the spinner message while running. */
+    update(message: string): void;
+    /** Stop and clear the spinner line. */
+    stop(): void;
+}
+/**
+ * Start a spinner. Returns a handle to stop it.
+ *
+ * Only activates when stderr is a TTY — in pipes / CI it becomes a no-op
+ * so output stays clean.
+ */
+export declare function startSpinner(message: string): Spinner;

package/dist/spinner.js

@@ -0,0 +1,37 @@
+/**
+ * Lightweight terminal spinner — zero dependencies.
+ *
+ * Shows a cycling animation (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) with an optional message
+ * while async work is in progress. Clears itself when stopped.
+ */
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const INTERVAL_MS = 80;
+/**
+ * Start a spinner. Returns a handle to stop it.
+ *
+ * Only activates when stderr is a TTY — in pipes / CI it becomes a no-op
+ * so output stays clean.
+ */
+export function startSpinner(message) {
+    // No-op in non-TTY environments (piped output, CI, etc.)
+    if (!process.stderr.isTTY) {
+        return { update() { }, stop() { } };
+    }
+    let frame = 0;
+    let text = message;
+    const timer = setInterval(() => {
+        const line = `\r  ${FRAMES[frame % FRAMES.length]} ${text}`;
+        process.stderr.write(line);
+        frame++;
+    }, INTERVAL_MS);
+    return {
+        update(msg) {
+            text = msg;
+        },
+        stop() {
+            clearInterval(timer);
+            // Clear the spinner line
+            process.stderr.write('\r' + ' '.repeat((text.length || 0) + 6) + '\r');
+        },
+    };
+}