@yangfei_93sky/biocli 0.2.0

package/dist/databases/string-db.d.ts

@@ -0,0 +1,19 @@
+/**
+ * STRING database backend for biocli.
+ *
+ * STRING API (https://string-db.org/api):
+ *   - No authentication required (optional API key for batch jobs)
+ *   - Rate limit: 1 request per second (documented)
+ *   - Response format: JSON via /api/json/..., also supports TSV, XML, image
+ *   - Multiple identifiers separated by %0d (newline-encoded)
+ *   - species parameter: NCBI taxonomy ID (9606 for human)
+ */
+import { type DatabaseBackend } from './index.js';
+/** Build a STRING API URL. Format is embedded in path: /api/{format}/{endpoint} */
+export declare function buildStringUrl(endpoint: string, params?: Record<string, string>): string;
+/**
+ * Encode multiple identifiers for STRING API.
+ * STRING uses %0d (URL-encoded newline) as separator.
+ */
+export declare function encodeStringIds(ids: string[]): string;
+export declare const stringBackend: DatabaseBackend;

package/dist/databases/string-db.js

@@ -0,0 +1,105 @@
+/**
+ * STRING database backend for biocli.
+ *
+ * STRING API (https://string-db.org/api):
+ *   - No authentication required (optional API key for batch jobs)
+ *   - Rate limit: 1 request per second (documented)
+ *   - Response format: JSON via /api/json/..., also supports TSV, XML, image
+ *   - Multiple identifiers separated by %0d (newline-encoded)
+ *   - species parameter: NCBI taxonomy ID (9606 for human)
+ */
+import { getRateLimiterForDatabase } from '../rate-limiter.js';
+import { ApiError } from '../errors.js';
+import { sleep } from '../utils.js';
+import { registerBackend } from './index.js';
+const BASE_URL = 'https://string-db.org/api';
+const MAX_RETRIES = 2;
+const BASE_RETRY_DELAY_MS = 1000;
+/** Build a STRING API URL. Format is embedded in path: /api/{format}/{endpoint} */
+export function buildStringUrl(endpoint, params) {
+    const url = new URL(`${BASE_URL}/json/${endpoint}`);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, v);
+        }
+    }
+    // Identify ourselves
+    if (!url.searchParams.has('caller_identity')) {
+        url.searchParams.set('caller_identity', 'biocli');
+    }
+    return url.toString();
+}
+/**
+ * Encode multiple identifiers for STRING API.
+ * STRING uses %0d (URL-encoded newline) as separator.
+ */
+export function encodeStringIds(ids) {
+    return ids.join('%0d');
+}
+/** Low-level STRING fetch with rate limiting and retry. */
+async function stringFetch(url, opts) {
+    if (!opts?.skipRateLimit) {
+        const limiter = getRateLimiterForDatabase('string', 1);
+        await limiter.acquire();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(url, {
+                method: opts?.method ?? 'GET',
+                headers: { 'Accept': 'application/json', ...opts?.headers },
+                body: opts?.body,
+            });
+            if (response.status === 429 || response.status === 503) {
+                if (attempt < MAX_RETRIES) {
+                    await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                    continue;
+                }
+                throw new ApiError('STRING API rate limit exceeded. Try again in a few seconds.');
+            }
+            if (!response.ok) {
+                throw new ApiError(`STRING API returned HTTP ${response.status}: ${response.statusText}`);
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                throw err;
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw new ApiError(`STRING request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown error'}`);
+}
+function createContext() {
+    return {
+        databaseId: 'string',
+        async fetch(url, opts) {
+            return stringFetch(url, opts);
+        },
+        async fetchJson(url, opts) {
+            const response = await stringFetch(url, opts);
+            return response.json();
+        },
+        async fetchXml(url, opts) {
+            const response = await stringFetch(url, opts);
+            return response.text();
+        },
+        async fetchText(url, opts) {
+            const response = await stringFetch(url, opts);
+            return response.text();
+        },
+    };
+}
+export const stringBackend = {
+    id: 'string',
+    name: 'STRING',
+    baseUrl: BASE_URL,
+    rateLimit: 1,
+    createContext,
+};
+registerBackend(stringBackend);

package/dist/databases/uniprot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * UniProt database backend for biocli.
+ *
+ * UniProt REST API (https://rest.uniprot.org):
+ *   - No authentication required
+ *   - Rate limit: ~200 req/s (we cap at 50/s to be polite)
+ *   - Response format: JSON (default), XML, TSV, FASTA
+ *   - Pagination via Link headers
+ */
+import { type DatabaseBackend } from './index.js';
+/** Build a UniProt API URL with query parameters. */
+export declare function buildUniprotUrl(path: string, params?: Record<string, string>): string;
+export declare const uniprotBackend: DatabaseBackend;

package/dist/databases/uniprot.js

@@ -0,0 +1,110 @@
+/**
+ * UniProt database backend for biocli.
+ *
+ * UniProt REST API (https://rest.uniprot.org):
+ *   - No authentication required
+ *   - Rate limit: ~200 req/s (we cap at 50/s to be polite)
+ *   - Response format: JSON (default), XML, TSV, FASTA
+ *   - Pagination via Link headers
+ */
+import { getRateLimiterForDatabase } from '../rate-limiter.js';
+import { ApiError } from '../errors.js';
+import { sleep } from '../utils.js';
+import { registerBackend } from './index.js';
+const BASE_URL = 'https://rest.uniprot.org';
+const MAX_RETRIES = 2;
+const BASE_RETRY_DELAY_MS = 500;
+/** Build a UniProt API URL with query parameters. */
+export function buildUniprotUrl(path, params) {
+    const url = new URL(`${BASE_URL}${path}`);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, v);
+        }
+    }
+    return url.toString();
+}
+/** Low-level UniProt fetch with rate limiting and retry. */
+async function uniprotFetch(url, opts) {
+    const parsed = new URL(url);
+    if (opts?.params) {
+        for (const [k, v] of Object.entries(opts.params)) {
+            if (v !== undefined && v !== '')
+                parsed.searchParams.set(k, v);
+        }
+    }
+    const finalUrl = parsed.toString();
+    if (!opts?.skipRateLimit) {
+        const limiter = getRateLimiterForDatabase('uniprot', 50);
+        await limiter.acquire();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(finalUrl, {
+                method: opts?.method ?? 'GET',
+                headers: {
+                    'Accept': 'application/json',
+                    ...opts?.headers,
+                },
+                body: opts?.body,
+            });
+            if (response.status === 429) {
+                if (attempt < MAX_RETRIES) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const delayMs = retryAfter
+                        ? parseInt(retryAfter, 10) * 1000
+                        : BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+                    await sleep(delayMs);
+                    continue;
+                }
+                throw new ApiError('UniProt API rate limit exceeded');
+            }
+            if (!response.ok) {
+                throw new ApiError(`UniProt API returned HTTP ${response.status}: ${response.statusText}`, `Request URL: ${finalUrl}`);
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                throw err;
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw new ApiError(`UniProt request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown error'}`);
+}
+/** Create a UniProt HttpContext. */
+function createContext() {
+    return {
+        databaseId: 'uniprot',
+        async fetch(url, opts) {
+            return uniprotFetch(url, opts);
+        },
+        async fetchJson(url, opts) {
+            const response = await uniprotFetch(url, opts);
+            return response.json();
+        },
+        async fetchXml(url, opts) {
+            const response = await uniprotFetch(url, opts);
+            return response.text(); // caller can parse XML if needed
+        },
+        async fetchText(url, opts) {
+            const response = await uniprotFetch(url, opts);
+            return response.text();
+        },
+    };
+}
+// ── Backend registration ─────────────────────────────────────────────────────
+export const uniprotBackend = {
+    id: 'uniprot',
+    name: 'UniProt',
+    baseUrl: BASE_URL,
+    rateLimit: 50,
+    createContext,
+};
+registerBackend(uniprotBackend);

package/dist/discovery.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI discovery: finds YAML/TS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers all YAML commands instantly without runtime YAML parsing.
+ *    TS modules are loaded lazily only when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+/** Built-in CLIs directory: dist/clis/ or src/clis/ */
+export declare const BUILTIN_CLIS_DIR: string;
+/** User runtime directory: ~/.biocli */
+export declare const USER_BIOCLI_DIR: string;
+/** @deprecated Use USER_BIOCLI_DIR. */
+export declare const USER_NCBICLI_DIR: string;
+/** User CLIs directory: ~/.biocli/clis/ */
+export declare const USER_CLIS_DIR: string;
+/** Plugins directory: ~/.biocli/plugins/ */
+export declare const PLUGINS_DIR: string;
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export declare function discoverClis(...dirs: string[]): Promise<void>;
+/**
+ * Discover and load plugins from ~/.biocli/plugins/.
+ *
+ * Each plugin is either:
+ * - A directory with a package.json (npm package)
+ * - A single .ts/.js file
+ */
+export declare function discoverPlugins(): Promise<void>;

package/dist/discovery.js

@@ -0,0 +1,235 @@
+/**
+ * CLI discovery: finds YAML/TS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers all YAML commands instantly without runtime YAML parsing.
+ *    TS modules are loaded lazily only when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import { Strategy, registerCommand } from './registry.js';
+import { getErrorMessage } from './errors.js';
+import { parseYamlCli } from './yaml-schema.js';
+import { isRecord } from './utils.js';
+// ── Directory paths ─────────────────────────────────────────────────────────
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Built-in CLIs directory: dist/clis/ or src/clis/ */
+export const BUILTIN_CLIS_DIR = path.join(__dirname, 'clis');
+/** User runtime directory: ~/.biocli */
+export const USER_BIOCLI_DIR = path.join(os.homedir(), '.biocli');
+/** @deprecated Use USER_BIOCLI_DIR. */
+export const USER_NCBICLI_DIR = USER_BIOCLI_DIR;
+/** User CLIs directory: ~/.biocli/clis/ */
+export const USER_CLIS_DIR = path.join(USER_BIOCLI_DIR, 'clis');
+/** Plugins directory: ~/.biocli/plugins/ */
+export const PLUGINS_DIR = path.join(USER_BIOCLI_DIR, 'plugins');
+/** Matches files that register commands via cli() or lifecycle hooks */
+const PLUGIN_MODULE_PATTERN = /\b(?:cli|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
+// ── Strategy parser ─────────────────────────────────────────────────────────
+function parseStrategy(rawStrategy) {
+    if (!rawStrategy)
+        return Strategy.PUBLIC;
+    const upper = rawStrategy.toUpperCase();
+    if (upper === 'API_KEY')
+        return Strategy.API_KEY;
+    return Strategy.PUBLIC;
+}
+// ── Main discovery entry point ──────────────────────────────────────────────
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export async function discoverClis(...dirs) {
+    for (const dir of dirs) {
+        // Fast path: try manifest first (production / post-build)
+        const manifestPath = path.resolve(dir, '..', 'cli-manifest.json');
+        try {
+            await fs.promises.access(manifestPath);
+            const loaded = await loadFromManifest(manifestPath, dir);
+            if (loaded)
+                continue; // Skip filesystem scan only when manifest is usable
+        }
+        catch {
+            // Fall through to filesystem scan
+        }
+        await discoverClisFromFs(dir);
+    }
+}
+// ── Fast path: manifest loading ─────────────────────────────────────────────
+/**
+ * Fast-path: register commands from pre-compiled manifest.
+ * YAML pipelines are inlined — zero YAML parsing at runtime.
+ * TS modules are deferred — loaded lazily on first execution.
+ */
+async function loadFromManifest(manifestPath, clisDir) {
+    try {
+        const raw = await fs.promises.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(raw);
+        for (const entry of manifest) {
+            if (entry.type === 'yaml') {
+                // YAML pipelines fully inlined in manifest — register directly
+                const strategy = parseStrategy(entry.strategy);
+                const cmd = {
+                    site: entry.site,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                    description: entry.description ?? '',
+                    database: entry.database,
+                    strategy,
+                    args: entry.args ?? [],
+                    columns: entry.columns,
+                    pipeline: entry.pipeline,
+                    timeoutSeconds: entry.timeout,
+                    source: `manifest:${entry.site}/${entry.name}`,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
+                };
+                registerCommand(cmd);
+            }
+            else if (entry.type === 'ts' && entry.modulePath) {
+                // TS adapters: register a lightweight stub.
+                // The actual module is loaded lazily on first executeCommand().
+                const strategy = parseStrategy(entry.strategy ?? 'public');
+                const modulePath = path.resolve(clisDir, entry.modulePath);
+                const cmd = {
+                    site: entry.site,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                    description: entry.description ?? '',
+                    database: entry.database,
+                    strategy,
+                    args: entry.args ?? [],
+                    columns: entry.columns,
+                    timeoutSeconds: entry.timeout,
+                    source: modulePath,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
+                    _lazy: true,
+                    _modulePath: modulePath,
+                };
+                registerCommand(cmd);
+            }
+        }
+        return true;
+    }
+    catch (err) {
+        console.error(`[biocli] Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+// ── Fallback: filesystem scan ───────────────────────────────────────────────
+/**
+ * Check if a .ts/.js file looks like a CLI module (contains cli() call).
+ */
+async function isCliModule(filePath) {
+    try {
+        const content = await fs.promises.readFile(filePath, 'utf-8');
+        return PLUGIN_MODULE_PATTERN.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Fallback: traditional filesystem scan (used during development with tsx).
+ */
+async function discoverClisFromFs(dir) {
+    try {
+        await fs.promises.access(dir);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const sitePromises = entries
+        .filter(entry => entry.isDirectory())
+        .map(async (entry) => {
+        const site = entry.name;
+        // Skip hidden/shared directories
+        if (site.startsWith('.') || site.startsWith('_'))
+            return;
+        const siteDir = path.join(dir, site);
+        const files = await fs.promises.readdir(siteDir);
+        await Promise.all(files.map(async (file) => {
+            if (file.startsWith('.'))
+                return; // skip hidden/AppleDouble files
+            const filePath = path.join(siteDir, file);
+            if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                await registerYamlCli(filePath, site);
+            }
+            else if ((file.endsWith('.js') && !file.endsWith('.d.js')) ||
+                (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))) {
+                if (!(await isCliModule(filePath)))
+                    return;
+                await import(pathToFileURL(filePath).href).catch((err) => {
+                    console.error(`[biocli] Failed to load module ${filePath}: ${getErrorMessage(err)}`);
+                });
+            }
+        }));
+    });
+    await Promise.all(sitePromises);
+}
+async function registerYamlCli(filePath, defaultSite) {
+    try {
+        const raw = await fs.promises.readFile(filePath, 'utf-8');
+        const def = yaml.load(raw);
+        if (!isRecord(def))
+            return;
+        parseYamlCli(def, filePath, defaultSite);
+    }
+    catch (err) {
+        console.error(`[biocli] Failed to parse YAML ${filePath}: ${getErrorMessage(err)}`);
+    }
+}
+// ── Plugin discovery ────────────────────────────────────────────────────────
+/**
+ * Discover and load plugins from ~/.biocli/plugins/.
+ *
+ * Each plugin is either:
+ * - A directory with a package.json (npm package)
+ * - A single .ts/.js file
+ */
+export async function discoverPlugins() {
+    try {
+        await fs.promises.access(PLUGINS_DIR);
+    }
+    catch {
+        return; // No plugins directory — nothing to do
+    }
+    const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(PLUGINS_DIR, entry.name);
+        if (entry.isDirectory()) {
+            // Directory plugin: look for package.json with "main" entry
+            const pkgPath = path.join(fullPath, 'package.json');
+            try {
+                await fs.promises.access(pkgPath);
+                const pkg = JSON.parse(await fs.promises.readFile(pkgPath, 'utf-8'));
+                const mainFile = pkg.main ?? 'index.js';
+                const mainPath = path.resolve(fullPath, mainFile);
+                await import(pathToFileURL(mainPath).href);
+            }
+            catch (err) {
+                console.error(`[biocli] Failed to load plugin ${entry.name}: ${getErrorMessage(err)}`);
+            }
+        }
+        else if ((entry.name.endsWith('.js') && !entry.name.endsWith('.d.js')) ||
+            (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts'))) {
+            // Single-file plugin
+            try {
+                const content = await fs.promises.readFile(fullPath, 'utf-8');
+                if (PLUGIN_MODULE_PATTERN.test(content)) {
+                    await import(pathToFileURL(fullPath).href);
+                }
+            }
+            catch (err) {
+                console.error(`[biocli] Failed to load plugin ${entry.name}: ${getErrorMessage(err)}`);
+            }
+        }
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+interface CheckResult {
+    name: string;
+    value: string;
+    ok: boolean;
+    detail?: string;
+}
+export declare function runDoctor(): Promise<{
+    checks: CheckResult[];
+    allPassed: boolean;
+}>;
+export declare function formatDoctorText(checks: CheckResult[], allPassed: boolean): string;
+export declare function formatDoctorJson(checks: CheckResult[], allPassed: boolean): string;
+export {};