@yangfei_93sky/biocli 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Core type definitions for biocli.
+ *
+ * HttpContext is the primary execution context passed to every command
+ * function. It wraps database-aware HTTP fetching with built-in rate
+ * limiting, authentication injection, and response parsing.
+ */
+/** Metadata that commands can attach to results for the rendering layer. */
+export interface ResultMeta {
+    /** Total matching items from the API (e.g. esearch count), for "3 of N" display. */
+    totalCount?: number;
+    /** The original search query, used for keyword highlighting. */
+    query?: string;
+}
+/**
+ * Wraps a result array with optional display metadata.
+ *
+ * Commands return this via `withMeta(rows, meta)` — the commander-adapter
+ * extracts the meta and passes it to the output renderer.
+ */
+export interface ResultWithMeta<T = unknown> {
+    readonly __resultMeta: true;
+    rows: T[];
+    meta: ResultMeta;
+}
+/** Wrap command results with display metadata. */
+export declare function withMeta<T>(rows: T[], meta: ResultMeta): ResultWithMeta<T>;
+/** Type guard for ResultWithMeta. */
+export declare function hasResultMeta(v: unknown): v is ResultWithMeta;
+/**
+ * Standard result envelope for aggregation/workflow commands.
+ *
+ * Every high-level biocli command should return this shape so that
+ * AI agents and downstream scripts can consume results reliably.
+ */
+export interface BiocliResult<T = unknown> {
+    /** Primary result data. */
+    data: T;
+    /** Cross-database identifiers for the queried entity. */
+    ids: Record<string, string>;
+    /** Which databases contributed data. */
+    sources: string[];
+    /** Non-fatal issues: partial failures, ambiguous matches, missing fields. */
+    warnings: string[];
+    /** ISO timestamp of when the query was executed. */
+    queriedAt: string;
+    /** Organism context (scientific name). */
+    organism?: string;
+    /** The original query input. */
+    query: string;
+}
+/** Create a BiocliResult envelope. */
+export declare function wrapResult<T>(data: T, opts: {
+    ids?: Record<string, string>;
+    sources?: string[];
+    warnings?: string[];
+    organism?: string;
+    query: string;
+}): BiocliResult<T>;
+/** Options for a single HTTP request. Generic across all database backends. */
+export interface FetchOptions {
+    /** HTTP method (defaults to 'GET'). */
+    method?: string;
+    /** Additional HTTP headers. */
+    headers?: Record<string, string>;
+    /** URL query parameters (merged with any already in the URL). */
+    params?: Record<string, string>;
+    /** Request body (for POST requests). */
+    body?: string;
+    /** If true, skip the rate limiter for this request. */
+    skipRateLimit?: boolean;
+}
+/**
+ * @deprecated Use FetchOptions instead. Kept for backward compatibility
+ * with existing NCBI adapters.
+ */
+export type NcbiFetchOptions = FetchOptions;
+/**
+ * HTTP execution context provided to every command function.
+ *
+ * Each database backend creates its own HttpContext with the appropriate
+ * rate limiter, authentication, and response parsers baked in.
+ */
+export interface HttpContext {
+    /** Database backend ID this context is bound to (e.g. 'ncbi', 'uniprot'). */
+    databaseId: string;
+    /** Make an HTTP request and return the raw Response. */
+    fetch(url: string, opts?: FetchOptions): Promise<Response>;
+    /** Fetch a URL and parse the response body as XML, returning the parsed object. */
+    fetchXml(url: string, opts?: FetchOptions): Promise<unknown>;
+    /** Fetch a URL and parse the response body as JSON. */
+    fetchJson(url: string, opts?: FetchOptions): Promise<unknown>;
+    /** Fetch a URL and return the raw text body. */
+    fetchText(url: string, opts?: FetchOptions): Promise<string>;
+    /** Database-specific credentials (NCBI: api_key, email; etc.). */
+    credentials?: Record<string, string>;
+    /** @deprecated Use credentials?.api_key instead. */
+    apiKey?: string;
+    /** @deprecated Use credentials?.email instead. */
+    email?: string;
+}

package/dist/types.js

@@ -0,0 +1,27 @@
+/**
+ * Core type definitions for biocli.
+ *
+ * HttpContext is the primary execution context passed to every command
+ * function. It wraps database-aware HTTP fetching with built-in rate
+ * limiting, authentication injection, and response parsing.
+ */
+/** Wrap command results with display metadata. */
+export function withMeta(rows, meta) {
+    return { __resultMeta: true, rows, meta };
+}
+/** Type guard for ResultWithMeta. */
+export function hasResultMeta(v) {
+    return typeof v === 'object' && v !== null && v.__resultMeta === true;
+}
+/** Create a BiocliResult envelope. */
+export function wrapResult(data, opts) {
+    return {
+        data,
+        ids: opts.ids ?? {},
+        sources: opts.sources ?? [],
+        warnings: opts.warnings ?? [],
+        queriedAt: new Date().toISOString(),
+        organism: opts.organism,
+        query: opts.query,
+    };
+}

package/dist/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Simple utility functions for biocli.
+ */
+/** Clamp a numeric value to the inclusive range [min, max]. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Return a promise that resolves after the given number of milliseconds. */
+export declare function sleep(ms: number): Promise<void>;
+/** Type guard: returns true if the value is a non-null plain object. */
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/**
+ * Map an array through an async function with bounded concurrency.
+ *
+ * At most `concurrency` invocations of `fn` run simultaneously.
+ * Results are returned in the same order as the input items.
+ */
+export declare function mapConcurrent<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, concurrency: number): Promise<R[]>;

package/dist/utils.js

@@ -0,0 +1,40 @@
+/**
+ * Simple utility functions for biocli.
+ */
+/** Clamp a numeric value to the inclusive range [min, max]. */
+export function clamp(value, min, max) {
+    if (min > max)
+        throw new RangeError(`clamp: min (${min}) must be <= max (${max})`);
+    return value < min ? min : value > max ? max : value;
+}
+/** Return a promise that resolves after the given number of milliseconds. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Type guard: returns true if the value is a non-null plain object. */
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Map an array through an async function with bounded concurrency.
+ *
+ * At most `concurrency` invocations of `fn` run simultaneously.
+ * Results are returned in the same order as the input items.
+ */
+export async function mapConcurrent(items, fn, concurrency) {
+    if (concurrency < 1)
+        throw new RangeError('concurrency must be >= 1');
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const idx = nextIndex++;
+            results[idx] = await fn(items[idx], idx);
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}

package/dist/validate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * YAML adapter definition validator.
+ *
+ * Validates that YAML CLI definitions have the correct structure and
+ * reference only known pipeline steps.
+ */
+export interface ValidationError {
+    file: string;
+    errors: string[];
+}
+/**
+ * Validate a single YAML CLI definition file.
+ *
+ * Checks:
+ * - File is valid YAML
+ * - Top-level is an object
+ * - Required fields present (name or can be derived from filename)
+ * - Pipeline steps reference known step handlers
+ * - Args have valid types
+ *
+ * @returns Array of error messages (empty if valid)
+ */
+export declare function validateYamlCli(filePath: string): string[];
+/**
+ * Validate all YAML CLI definitions in a directory (recursively scanning site subdirs).
+ *
+ * @returns Array of ValidationError objects for files with issues
+ */
+export declare function validateAll(cliDir: string): ValidationError[];

package/dist/validate.js

@@ -0,0 +1,136 @@
+/**
+ * YAML adapter definition validator.
+ *
+ * Validates that YAML CLI definitions have the correct structure and
+ * reference only known pipeline steps.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { isRecord } from './utils.js';
+import { getKnownStepNames } from './pipeline/index.js';
+/**
+ * Validate a single YAML CLI definition file.
+ *
+ * Checks:
+ * - File is valid YAML
+ * - Top-level is an object
+ * - Required fields present (name or can be derived from filename)
+ * - Pipeline steps reference known step handlers
+ * - Args have valid types
+ *
+ * @returns Array of error messages (empty if valid)
+ */
+export function validateYamlCli(filePath) {
+    const errors = [];
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        errors.push(`Cannot read file: ${err instanceof Error ? err.message : String(err)}`);
+        return errors;
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(content);
+    }
+    catch (err) {
+        errors.push(`Invalid YAML: ${err instanceof Error ? err.message : String(err)}`);
+        return errors;
+    }
+    if (!isRecord(parsed)) {
+        errors.push('Top-level value must be an object (mapping)');
+        return errors;
+    }
+    const def = parsed;
+    // Check description
+    if (!def.description) {
+        errors.push('Missing "description" field');
+    }
+    // Validate strategy if present
+    const validStrategies = ['public', 'api_key'];
+    if (def.strategy && !validStrategies.includes(def.strategy.toLowerCase())) {
+        errors.push(`Invalid strategy "${def.strategy}". Must be one of: ${validStrategies.join(', ')}`);
+    }
+    // Validate args
+    if (def.args) {
+        if (!isRecord(def.args)) {
+            errors.push('"args" must be an object mapping arg names to definitions');
+        }
+        else {
+            const validArgTypes = ['str', 'string', 'int', 'number', 'bool', 'boolean'];
+            for (const [argName, argDef] of Object.entries(def.args)) {
+                if (argDef && typeof argDef === 'object' && 'type' in argDef) {
+                    const argType = argDef.type;
+                    if (argType && !validArgTypes.includes(argType)) {
+                        errors.push(`Arg "${argName}": invalid type "${argType}". Must be one of: ${validArgTypes.join(', ')}`);
+                    }
+                }
+            }
+        }
+    }
+    // Validate pipeline steps
+    if (def.pipeline) {
+        if (!Array.isArray(def.pipeline)) {
+            errors.push('"pipeline" must be an array of step objects');
+        }
+        else {
+            const knownSteps = getKnownStepNames();
+            for (let i = 0; i < def.pipeline.length; i++) {
+                const step = def.pipeline[i];
+                if (!isRecord(step)) {
+                    errors.push(`Pipeline step ${i}: must be an object`);
+                    continue;
+                }
+                const stepNames = Object.keys(step);
+                if (stepNames.length === 0) {
+                    errors.push(`Pipeline step ${i}: empty step object`);
+                    continue;
+                }
+                const stepName = stepNames[0];
+                if (!knownSteps.includes(stepName)) {
+                    errors.push(`Pipeline step ${i}: unknown step "${stepName}". Known steps: ${knownSteps.join(', ')}`);
+                }
+            }
+        }
+    }
+    // Validate columns
+    if (def.columns !== undefined && !Array.isArray(def.columns)) {
+        errors.push('"columns" must be an array of strings');
+    }
+    // Validate timeout
+    if (def.timeout !== undefined) {
+        if (typeof def.timeout !== 'number' || def.timeout <= 0) {
+            errors.push('"timeout" must be a positive number (seconds)');
+        }
+    }
+    return errors;
+}
+/**
+ * Validate all YAML CLI definitions in a directory (recursively scanning site subdirs).
+ *
+ * @returns Array of ValidationError objects for files with issues
+ */
+export function validateAll(cliDir) {
+    const results = [];
+    if (!fs.existsSync(cliDir)) {
+        return results;
+    }
+    const siteDirs = fs.readdirSync(cliDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith('.') && !d.name.startsWith('_'));
+    for (const siteDir of siteDirs) {
+        const sitePath = path.join(cliDir, siteDir.name);
+        const files = fs.readdirSync(sitePath);
+        for (const file of files) {
+            if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
+                continue;
+            const filePath = path.join(sitePath, file);
+            const errors = validateYamlCli(filePath);
+            if (errors.length > 0) {
+                results.push({ file: filePath, errors });
+            }
+        }
+    }
+    return results;
+}

package/dist/verify.d.ts

@@ -0,0 +1,20 @@
+/**
+ * biocli verify — Unified verification: validate + doctor + optional smoke.
+ *
+ * Runs all diagnostic checks in sequence and reports a summary.
+ */
+interface StepResult {
+    step: string;
+    ok: boolean;
+    detail: string;
+}
+export interface VerifyResult {
+    steps: StepResult[];
+    allPassed: boolean;
+}
+export declare function runVerify(opts?: {
+    smoke?: boolean;
+}): Promise<VerifyResult>;
+export declare function formatVerifyText(result: VerifyResult): string;
+export declare function formatVerifyJson(result: VerifyResult): string;
+export {};

package/dist/verify.js

@@ -0,0 +1,131 @@
+/**
+ * biocli verify — Unified verification: validate + doctor + optional smoke.
+ *
+ * Runs all diagnostic checks in sequence and reports a summary.
+ */
+import chalk from 'chalk';
+import { validateAll } from './validate.js';
+import { runDoctor } from './doctor.js';
+import { BUILTIN_CLIS_DIR } from './discovery.js';
+import { generateCompletion } from './completion.js';
+import { getConfigPath } from './config.js';
+import { getRegistry } from './registry.js';
+import { biocliResultSchema, resultWithMetaSchema } from './schema.js';
+import { getVersion } from './version.js';
+// ── Steps ────────────────────────────────────────────────────────────────────
+function runValidateStep() {
+    const errors = validateAll(BUILTIN_CLIS_DIR);
+    const totalErrors = errors.reduce((n, e) => n + e.errors.length, 0);
+    return {
+        step: 'validate',
+        ok: totalErrors === 0,
+        detail: totalErrors === 0
+            ? 'All YAML adapters valid'
+            : `${totalErrors} validation error(s) in ${errors.length} file(s)`,
+    };
+}
+async function runDoctorStep() {
+    const { checks, allPassed } = await runDoctor();
+    const failed = checks.filter(c => !c.ok);
+    return {
+        step: 'doctor',
+        ok: allPassed,
+        detail: allPassed
+            ? `All ${checks.length} checks passed`
+            : `${failed.length} check(s) failed: ${failed.map(c => c.name).join(', ')}`,
+    };
+}
+function runSmokeStep() {
+    const checks = [
+        {
+            name: 'version',
+            check: () => {
+                if (!getVersion() || getVersion() === '0.0.0') {
+                    throw new Error('invalid version');
+                }
+            },
+        },
+        {
+            name: 'list',
+            check: () => {
+                if (getRegistry().size === 0) {
+                    throw new Error('empty registry');
+                }
+            },
+        },
+        {
+            name: 'config path',
+            check: () => {
+                if (!getConfigPath().endsWith('/config.yaml')) {
+                    throw new Error('bad config path');
+                }
+            },
+        },
+        {
+            name: 'schema',
+            check: () => {
+                if (biocliResultSchema.title !== 'BiocliResult') {
+                    throw new Error('bad schema');
+                }
+            },
+        },
+        {
+            name: 'schema meta',
+            check: () => {
+                if (resultWithMetaSchema.title !== 'ResultWithMeta') {
+                    throw new Error('bad meta schema');
+                }
+            },
+        },
+        {
+            name: 'completion bash',
+            check: () => {
+                const script = generateCompletion('bash');
+                if (!script.includes('complete -F _biocli_completions biocli')) {
+                    throw new Error('bad completion');
+                }
+            },
+        },
+    ];
+    for (const smokeCheck of checks) {
+        try {
+            smokeCheck.check();
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'unknown error';
+            return { step: 'smoke', ok: false, detail: `${smokeCheck.name}: ${detail}` };
+        }
+    }
+    return { step: 'smoke', ok: true, detail: `Core smoke tests passed (${checks.length} checks)` };
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+export async function runVerify(opts = {}) {
+    const steps = [];
+    steps.push(runValidateStep());
+    steps.push(await runDoctorStep());
+    if (opts.smoke) {
+        steps.push(runSmokeStep());
+    }
+    return { steps, allPassed: steps.every(s => s.ok) };
+}
+// ── Formatters ───────────────────────────────────────────────────────────────
+export function formatVerifyText(result) {
+    const lines = ['', chalk.bold('biocli verify'), ''];
+    for (const step of result.steps) {
+        const status = step.ok ? chalk.green('PASS') : chalk.red('FAIL');
+        lines.push(`  ${step.step.padEnd(12)} ${status}  ${chalk.dim(step.detail)}`);
+    }
+    lines.push('');
+    if (result.allPassed) {
+        lines.push(chalk.green(`  All ${result.steps.length} steps passed.`));
+    }
+    else {
+        const passed = result.steps.filter(s => s.ok).length;
+        lines.push(chalk.yellow(`  ${passed}/${result.steps.length} steps passed.`));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatVerifyJson(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Version string reader for biocli.
+ *
+ * Reads the version from package.json at runtime. Handles both
+ * development (src/) and production (dist/) directory layouts.
+ */
+/**
+ * Return the current biocli version string from package.json.
+ *
+ * The result is cached after the first call. Falls back to '0.0.0'
+ * if package.json cannot be found or parsed.
+ */
+export declare function getVersion(): string;

package/dist/version.js

@@ -0,0 +1,36 @@
+/**
+ * Version string reader for biocli.
+ *
+ * Reads the version from package.json at runtime. Handles both
+ * development (src/) and production (dist/) directory layouts.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+let _version;
+/**
+ * Return the current biocli version string from package.json.
+ *
+ * The result is cached after the first call. Falls back to '0.0.0'
+ * if package.json cannot be found or parsed.
+ */
+export function getVersion() {
+    if (_version)
+        return _version;
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    // Try dist/../package.json first (production), then src/../package.json (dev)
+    for (const rel of ['..', '../..']) {
+        try {
+            const pkgPath = join(__dirname, rel, 'package.json');
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const v = pkg.version ?? '0.0.0';
+            _version = v;
+            return v;
+        }
+        catch {
+            // Try next relative path
+        }
+    }
+    _version = '0.0.0';
+    return _version;
+}

package/dist/xml-parser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * XML parsing wrapper for NCBI responses.
+ *
+ * Uses fast-xml-parser with NCBI-specific configuration:
+ *   - Attributes are preserved with '@_' prefix
+ *   - Text nodes use '#text' key
+ *   - Known NCBI elements that can repeat are always parsed as arrays
+ *     (even when only a single element is present in the response)
+ */
+/**
+ * Parse an XML string into a JavaScript object using NCBI-tuned settings.
+ *
+ * Pre-strips inline markup tags (<i>, <b>, <sup>, etc.) so their text
+ * content is preserved in the parent element's #text node.
+ *
+ * @param xml  Raw XML response body from NCBI.
+ * @returns    Parsed object tree.
+ */
+export declare function parseXml(xml: string): unknown;