@yangfei_93sky/biocli 0.2.0

package/dist/ncbi-fetch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * NCBI HTTP client — backward compatibility shim.
+ *
+ * All logic has moved to databases/ncbi.ts. This file re-exports
+ * everything so that existing adapter imports continue to work:
+ *
+ *   import { createHttpContext } from '../ncbi-fetch.js';
+ *   import { buildEutilsUrl } from '../ncbi-fetch.js';
+ */
+export { EUTILS_BASE, buildEutilsUrl, ncbiFetch, createHttpContext, ncbiBackend, } from './databases/ncbi.js';

package/dist/ncbi-fetch.js

@@ -0,0 +1,10 @@
+/**
+ * NCBI HTTP client — backward compatibility shim.
+ *
+ * All logic has moved to databases/ncbi.ts. This file re-exports
+ * everything so that existing adapter imports continue to work:
+ *
+ *   import { createHttpContext } from '../ncbi-fetch.js';
+ *   import { buildEutilsUrl } from '../ncbi-fetch.js';
+ */
+export { EUTILS_BASE, buildEutilsUrl, ncbiFetch, createHttpContext, ncbiBackend, } from './databases/ncbi.js';

package/dist/output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Output formatting: table, card, JSON, Markdown, CSV, YAML, plain.
+ *
+ * Ported from opencli/src/output.ts for biocli.
+ */
+export interface RenderOptions {
+    fmt?: string;
+    columns?: string[];
+    title?: string;
+    elapsed?: number;
+    source?: string;
+    footerExtra?: string;
+    /** Search query for keyword highlighting in table/plain output. */
+    query?: string;
+    /** Total result count from API (e.g. esearch count), for "3 of N" display. */
+    totalCount?: number;
+}
+export declare function render(data: unknown, opts?: RenderOptions): void;

package/dist/output.js

@@ -0,0 +1,394 @@
+/**
+ * Output formatting: table, card, JSON, Markdown, CSV, YAML, plain.
+ *
+ * Ported from opencli/src/output.ts for biocli.
+ */
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import yaml from 'js-yaml';
+function normalizeRows(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === 'object')
+        return [data];
+    return [{ value: data }];
+}
+function resolveColumns(rows, opts) {
+    return opts.columns ?? Object.keys(rows[0] ?? {});
+}
+/** Get terminal width, default to 80 if unavailable. */
+function termWidth() {
+    return process.stdout.columns
+        || (process.env.COLUMNS ? parseInt(process.env.COLUMNS, 10) : 0)
+        || 80;
+}
+/** Truncate text to maxLen, appending '…' if trimmed. */
+function truncateCell(text, maxLen) {
+    if (maxLen < 2)
+        return '…';
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 1) + '…';
+}
+// ── Column width allocation ───────────────────────────────────────────────────
+/**
+ * Minimum content widths for known column types.
+ * These are "content" widths (excluding the 2-char cell padding cli-table3 adds).
+ */
+const COL_MIN_CONTENT = {
+    pmid: 8,
+    uid: 8,
+    geneid: 6,
+    year: 4,
+    date: 10,
+    samples: 4,
+    type: 4,
+    symbol: 6,
+    chromosome: 4,
+};
+/**
+ * Priority weights: higher = gets more space when distributing surplus.
+ * Columns not listed default to 1.
+ */
+const COL_PRIORITY = {
+    title: 5,
+    name: 4,
+    abstract: 5,
+    summary: 4,
+    description: 4,
+    doi: 4,
+    journal: 3,
+    authors: 3,
+    condition: 3,
+    significance: 2,
+    organism: 2,
+    platform: 2,
+    accession: 2,
+};
+/**
+ * Allocate column widths so the table fits within terminal width.
+ *
+ * cli-table3 colWidths includes the 2-char padding (1 left + 1 right),
+ * so "colWidth = contentWidth + 2". Border chars (│) add (n+1) total.
+ *
+ * Total table width = sum(colWidths) + (n + 1)
+ */
+function allocateColumnWidths(columns, rows) {
+    const n = columns.length;
+    const tw = termWidth();
+    const borderChars = n + 1; // │ before each column + │ at the end
+    const available = tw - borderChars; // total space for all colWidths
+    // Measure natural content width per column (max of header and all row values)
+    const natural = columns.map(col => {
+        let maxW = capitalize(col).length;
+        for (const row of rows) {
+            const v = row[col];
+            const len = v === null || v === undefined ? 0 : String(v).length;
+            if (len > maxW)
+                maxW = len;
+        }
+        return maxW + 2; // +2 for cell padding → this is the colWidth value
+    });
+    const totalNatural = natural.reduce((a, b) => a + b, 0);
+    // If everything fits naturally, use natural widths
+    if (totalNatural <= available)
+        return natural;
+    // Otherwise, compute minimum widths and distribute remaining space by priority
+    const mins = columns.map(col => {
+        const headerW = capitalize(col).length;
+        const knownMin = COL_MIN_CONTENT[col.toLowerCase()];
+        const contentMin = knownMin ?? Math.min(headerW, 8);
+        return Math.max(contentMin, headerW) + 2; // +2 for padding
+    });
+    const totalMins = mins.reduce((a, b) => a + b, 0);
+    if (totalMins >= available) {
+        // Even minimums don't fit — proportionally shrink minimums
+        const ratio = available / totalMins;
+        return mins.map(m => Math.max(4, Math.floor(m * ratio)));
+    }
+    // Distribute surplus space proportionally by priority × natural demand
+    const surplus = available - totalMins;
+    const wants = columns.map((col, i) => {
+        const priority = COL_PRIORITY[col.toLowerCase()] ?? 1;
+        const extra = Math.max(0, natural[i] - mins[i]);
+        return priority * extra;
+    });
+    const totalWant = wants.reduce((a, b) => a + b, 0);
+    if (totalWant === 0)
+        return mins;
+    return mins.map((min, i) => {
+        const share = Math.floor(surplus * wants[i] / totalWant);
+        // Never exceed the natural width (no point adding empty space)
+        return Math.min(min + share, natural[i]);
+    });
+}
+// ── Terminal hyperlinks (OSC 8) ───────────────────────────────────────────────
+/** Whether the terminal supports OSC 8 hyperlinks. */
+const HYPERLINKS_SUPPORTED = !!(process.stdout.isTTY && process.env.TERM_PROGRAM !== 'Apple_Terminal');
+/** Wrap text in an OSC 8 clickable hyperlink (no-op if unsupported). */
+function hyperlink(text, url) {
+    if (!HYPERLINKS_SUPPORTED)
+        return text;
+    return `\u001b]8;;${url}\u0007${text}\u001b]8;;\u0007`;
+}
+/**
+ * Known column names → URL patterns for automatic hyperlinking.
+ * Returns the URL if the value can be linked, undefined otherwise.
+ */
+function autoLinkUrl(column, value) {
+    const col = column.toLowerCase();
+    if (col === 'doi' && value && !value.startsWith('http')) {
+        return `https://doi.org/${value}`;
+    }
+    if (col === 'pmid' && /^\d+$/.test(value)) {
+        return `https://pubmed.ncbi.nlm.nih.gov/${value}/`;
+    }
+    if (col === 'geneid' && /^\d+$/.test(value)) {
+        return `https://www.ncbi.nlm.nih.gov/gene/${value}`;
+    }
+    if (col === 'accession') {
+        if (/^GSE\d+$/i.test(value))
+            return `https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=${value}`;
+        if (/^SRR\d+$/i.test(value))
+            return `https://www.ncbi.nlm.nih.gov/sra/${value}`;
+        if (/^RCV\d+$/i.test(value))
+            return `https://www.ncbi.nlm.nih.gov/clinvar/${value}/`;
+    }
+    if (col === 'uid' && /^\d+$/.test(value)) {
+        // ClinVar UID
+        return `https://www.ncbi.nlm.nih.gov/clinvar/variation/${value}/`;
+    }
+    return undefined;
+}
+/** Apply hyperlink to a cell value if the column is linkable. */
+function linkCell(column, text) {
+    const url = autoLinkUrl(column, text);
+    return url ? hyperlink(text, url) : text;
+}
+/** Highlight query keywords in text using chalk.bold.underline. */
+function highlightQuery(text, query) {
+    if (!query || !text)
+        return text;
+    // Split query into individual words, escape regex chars
+    const words = query.split(/\s+/).filter(w => w.length > 1);
+    if (!words.length)
+        return text;
+    const escaped = words.map(w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const re = new RegExp(`(${escaped.join('|')})`, 'gi');
+    return text.replace(re, (match) => chalk.bold.underline(match));
+}
+export function render(data, opts = {}) {
+    const fmt = opts.fmt ?? 'table';
+    if (data === null || data === undefined) {
+        console.log(data);
+        return;
+    }
+    switch (fmt) {
+        case 'json':
+            renderJson(data);
+            break;
+        case 'plain':
+            renderPlain(data, opts);
+            break;
+        case 'md':
+        case 'markdown':
+            renderMarkdown(data, opts);
+            break;
+        case 'csv':
+            renderCsv(data, opts);
+            break;
+        case 'yaml':
+        case 'yml':
+            renderYaml(data);
+            break;
+        default:
+            renderTable(data, opts);
+            break;
+    }
+}
+// ── Card view for single records ──────────────────────────────────────────────
+function renderCard(row, columns, opts) {
+    const tw = termWidth();
+    const labelWidth = Math.max(...columns.map(c => capitalize(c).length)) + 2;
+    const valueWidth = tw - labelWidth - 6; // padding and borders
+    console.log();
+    console.log(chalk.dim(`  ── ${opts.title ?? 'result'} ${'─'.repeat(Math.max(0, tw - (opts.title?.length ?? 6) - 8))}`));
+    for (const col of columns) {
+        const raw = row[col];
+        const value = raw === null || raw === undefined ? '' : String(raw);
+        const label = capitalize(col);
+        if (!value)
+            continue;
+        // Long text fields get their own block
+        if (value.length > valueWidth) {
+            console.log(chalk.bold.cyan(`  ${label}`));
+            // Word-wrap the value
+            const wrapped = wordWrap(highlightQuery(value, opts.query), tw - 4);
+            for (const line of wrapped) {
+                console.log(`    ${line}`);
+            }
+        }
+        else {
+            const paddedLabel = label.padEnd(labelWidth);
+            const displayed = linkCell(col, highlightQuery(value, opts.query));
+            console.log(`  ${chalk.bold.cyan(paddedLabel)}${displayed}`);
+        }
+    }
+    // Footer
+    const footer = [];
+    if (opts.elapsed)
+        footer.push(`${opts.elapsed.toFixed(1)}s`);
+    if (opts.source)
+        footer.push(opts.source);
+    if (opts.footerExtra)
+        footer.push(opts.footerExtra);
+    console.log(chalk.dim(`  ${'─'.repeat(Math.max(0, tw - 4))}${footer.length ? '\n  ' + footer.join(' · ') : ''}`));
+}
+/** Simple word-wrap: break text into lines of at most `width` characters. */
+function wordWrap(text, width) {
+    if (text.length <= width)
+        return [text];
+    const lines = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= width) {
+            lines.push(remaining);
+            break;
+        }
+        // Find last space within width
+        let breakAt = remaining.lastIndexOf(' ', width);
+        if (breakAt <= 0)
+            breakAt = width;
+        lines.push(remaining.slice(0, breakAt));
+        remaining = remaining.slice(breakAt).trimStart();
+    }
+    return lines;
+}
+// ── Table view ────────────────────────────────────────────────────────────────
+function renderTable(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length) {
+        console.log();
+        console.log(chalk.yellow('  No results found'));
+        if (opts.query) {
+            console.log(chalk.dim(`  Try a broader search term or check spelling`));
+        }
+        return;
+    }
+    const columns = resolveColumns(rows, opts);
+    // Single record → card view (much more readable than a 1-row wide table)
+    if (rows.length === 1) {
+        renderCard(rows[0], columns, opts);
+        return;
+    }
+    // Compute column widths that fit within the terminal
+    const colWidths = allocateColumnWidths(columns, rows);
+    const header = columns.map(c => capitalize(c));
+    const table = new Table({
+        head: header.map(h => chalk.bold(h)),
+        style: { head: [], border: [] },
+        colWidths,
+    });
+    for (const row of rows) {
+        table.push(columns.map((c, i) => {
+            const v = row[c];
+            if (v === null || v === undefined)
+                return '';
+            let text = String(v);
+            // Truncate plain text to fit column content width FIRST,
+            // then apply ANSI formatting. This avoids breaking escape sequences
+            // and prevents invisible bytes from inflating width.
+            const contentW = colWidths[i] - 2; // subtract cell padding
+            text = truncateCell(text, contentW);
+            // Apply highlighting on truncated plain text (safe — chalk codes
+            // are handled by cli-table3's strip-ansi for width calculation).
+            // NOTE: No OSC 8 hyperlinks in table cells — they break width calc.
+            return highlightQuery(text, opts.query);
+        }));
+    }
+    console.log();
+    if (opts.title)
+        console.log(chalk.dim(`  ${opts.title}`));
+    console.log(table.toString());
+    renderFooter(rows.length, opts);
+}
+// ── Footer helper ─────────────────────────────────────────────────────────────
+function renderFooter(count, opts) {
+    const footer = [];
+    const hasMore = opts.totalCount && opts.totalCount > count;
+    if (hasMore) {
+        footer.push(`${count} of ${opts.totalCount.toLocaleString()} items`);
+    }
+    else {
+        footer.push(`${count} items`);
+    }
+    if (opts.elapsed)
+        footer.push(`${opts.elapsed.toFixed(1)}s`);
+    if (opts.source)
+        footer.push(opts.source);
+    if (opts.footerExtra)
+        footer.push(opts.footerExtra);
+    console.log(chalk.dim(footer.join(' · ')));
+    if (hasMore) {
+        console.log(chalk.dim(`  Use --limit <n> to show more results`));
+    }
+}
+function renderJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+function renderPlain(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return;
+    // Single-row single-field shortcuts for simple commands.
+    if (rows.length === 1) {
+        const row = rows[0];
+        const entries = Object.entries(row);
+        if (entries.length === 1) {
+            const [key, value] = entries[0];
+            if (key === 'response' || key === 'content' || key === 'text' || key === 'value') {
+                console.log(highlightQuery(String(value ?? ''), opts.query));
+                return;
+            }
+        }
+    }
+    rows.forEach((row, index) => {
+        const entries = Object.entries(row).filter(([, value]) => value !== undefined && value !== null && String(value) !== '');
+        entries.forEach(([key, value]) => {
+            console.log(`${key}: ${highlightQuery(String(value), opts.query)}`);
+        });
+        if (index < rows.length - 1)
+            console.log('');
+    });
+}
+function renderMarkdown(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return;
+    const columns = resolveColumns(rows, opts);
+    console.log('| ' + columns.join(' | ') + ' |');
+    console.log('| ' + columns.map(() => '---').join(' | ') + ' |');
+    for (const row of rows) {
+        console.log('| ' + columns.map(c => String(row[c] ?? '')).join(' | ') + ' |');
+    }
+}
+function renderCsv(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return;
+    const columns = resolveColumns(rows, opts);
+    console.log(columns.join(','));
+    for (const row of rows) {
+        console.log(columns.map(c => {
+            const v = String(row[c] ?? '');
+            return v.includes(',') || v.includes('"') || v.includes('\n') || v.includes('\r')
+                ? `"${v.replace(/"/g, '""')}"` : v;
+        }).join(','));
+    }
+}
+function renderYaml(data) {
+    console.log(yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true }));
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/dist/pipeline/executor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pipeline executor: runs YAML pipeline steps sequentially.
+ *
+ * Adapted from opencli:
+ * - No browser retry logic
+ * - No browser window close on failure
+ * - Sequential step execution with getStepHandler() from registry
+ */
+import type { HttpContext } from '../types.js';
+/**
+ * Execute a pipeline (array of step objects) sequentially.
+ *
+ * Each step object has a single key (the step name) whose value is the params.
+ * Data flows from one step to the next: the return value of step N becomes
+ * the `data` argument for step N+1.
+ *
+ * @param pipeline - Array of step objects, e.g. [{ fetch: '...' }, { select: 'result.items' }]
+ * @param ctx      - HttpContext for NCBI API access (may be null for pure transforms)
+ * @param args     - User-provided arguments from the command invocation
+ * @returns The final data value after all steps have executed
+ */
+export declare function executePipeline(pipeline: Record<string, unknown>[], ctx: HttpContext | null, args: Record<string, unknown>): Promise<unknown>;

package/dist/pipeline/executor.js

@@ -0,0 +1,40 @@
+/**
+ * Pipeline executor: runs YAML pipeline steps sequentially.
+ *
+ * Adapted from opencli:
+ * - No browser retry logic
+ * - No browser window close on failure
+ * - Sequential step execution with getStepHandler() from registry
+ */
+import { getStepHandler } from './registry.js';
+/**
+ * Execute a pipeline (array of step objects) sequentially.
+ *
+ * Each step object has a single key (the step name) whose value is the params.
+ * Data flows from one step to the next: the return value of step N becomes
+ * the `data` argument for step N+1.
+ *
+ * @param pipeline - Array of step objects, e.g. [{ fetch: '...' }, { select: 'result.items' }]
+ * @param ctx      - HttpContext for NCBI API access (may be null for pure transforms)
+ * @param args     - User-provided arguments from the command invocation
+ * @returns The final data value after all steps have executed
+ */
+export async function executePipeline(pipeline, ctx, args) {
+    let data = undefined;
+    for (let i = 0; i < pipeline.length; i++) {
+        const step = pipeline[i];
+        if (!step || typeof step !== 'object')
+            continue;
+        const entries = Object.entries(step);
+        if (entries.length === 0)
+            continue;
+        const [stepName, params] = entries[0];
+        const handler = getStepHandler(stepName);
+        if (!handler) {
+            throw new Error(`Unknown pipeline step "${stepName}" at index ${i}. ` +
+                `Known steps: ${(await import('./registry.js')).getKnownStepNames().join(', ')}`);
+        }
+        data = await handler(ctx, params, data, args);
+    }
+    return data;
+}

package/dist/pipeline/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pipeline engine — public API re-exports.
+ */
+export { executePipeline } from './executor.js';
+export { getStepHandler, getKnownStepNames } from './registry.js';
+export { renderTemplate, renderValue } from './template.js';

package/dist/pipeline/index.js

@@ -0,0 +1,6 @@
+/**
+ * Pipeline engine — public API re-exports.
+ */
+export { executePipeline } from './executor.js';
+export { getStepHandler, getKnownStepNames } from './registry.js';
+export { renderTemplate, renderValue } from './template.js';

package/dist/pipeline/registry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dynamic registry for pipeline steps.
+ *
+ * Only data pipeline steps are registered (no browser steps).
+ * Allows core and third-party plugins to register custom YAML operations.
+ */
+import type { HttpContext } from '../types.js';
+export type StepHandler = (ctx: HttpContext | null, params: unknown, data: unknown, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Get a registered step handler by name.
+ */
+export declare function getStepHandler(name: string): StepHandler | undefined;
+/**
+ * List all registered step names (useful for validation / help output).
+ */
+export declare function getKnownStepNames(): string[];

package/dist/pipeline/registry.js

@@ -0,0 +1,31 @@
+/**
+ * Dynamic registry for pipeline steps.
+ *
+ * Only data pipeline steps are registered (no browser steps).
+ * Allows core and third-party plugins to register custom YAML operations.
+ */
+import { handleFetch } from './steps/fetch.js';
+import { handleSelect, handleMap, handleFilter, handleSort, handleLimit, } from './steps/transform.js';
+import { handleXmlParse } from './steps/xml-parse.js';
+const stepRegistry = new Map();
+// ── Register core steps ─────────────────────────────────────────────────────
+stepRegistry.set('fetch', handleFetch);
+stepRegistry.set('select', handleSelect);
+stepRegistry.set('map', handleMap);
+stepRegistry.set('filter', handleFilter);
+stepRegistry.set('sort', handleSort);
+stepRegistry.set('limit', handleLimit);
+stepRegistry.set('xml-parse', handleXmlParse);
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Get a registered step handler by name.
+ */
+export function getStepHandler(name) {
+    return stepRegistry.get(name);
+}
+/**
+ * List all registered step names (useful for validation / help output).
+ */
+export function getKnownStepNames() {
+    return [...stepRegistry.keys()];
+}

package/dist/pipeline/steps/fetch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pipeline step: fetch — HTTP API requests for NCBI endpoints.
+ *
+ * Adapted from opencli:
+ * - No browser-related fetch paths (no page.evaluate, no fetchBatchInBrowser)
+ * - Always uses Node.js built-in fetch()
+ * - Automatic API key / email injection via HttpContext
+ * - Rate limiting integration via HttpContext.fetch() or standalone rate limiter
+ * - XML auto-detection: if Content-Type contains 'xml', auto-parse with parseXml()
+ * - Per-item fetch pattern (when data is array and URL contains `item`)
+ * - Configurable concurrency (default 5)
+ */
+import type { HttpContext } from '../../types.js';
+/**
+ * Pipeline fetch step handler.
+ *
+ * Params can be:
+ * - A string (URL template)
+ * - An object with: url, method, params, headers, concurrency
+ */
+export declare function handleFetch(ctx: HttpContext | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;