@yangfei_93sky/biocli 0.2.0

package/dist/xml-parser.js

@@ -0,0 +1,119 @@
+/**
+ * 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)
+ */
+import { XMLParser } from 'fast-xml-parser';
+/**
+ * Set of NCBI XML element names that should always be parsed as arrays.
+ *
+ * When only a single child element exists, fast-xml-parser would normally
+ * return it as a scalar. Listing these tags here ensures they are always
+ * wrapped in an array, making downstream code simpler and more robust.
+ */
+const ARRAY_TAGS = new Set([
+    // PubMed
+    'PubmedArticle',
+    'PubmedBookArticle',
+    'Author',
+    'MeshHeading',
+    'Chemical',
+    'PublicationType',
+    'ArticleId',
+    'Keyword',
+    'Grant',
+    'Reference',
+    'ReferenceList',
+    'AbstractText',
+    'Affiliation',
+    'AffiliationInfo',
+    'Investigator',
+    'DataBank',
+    'AccessionNumber',
+    'CommentsCorrections',
+    // E-utilities generic
+    'Id',
+    'Item',
+    'Link',
+    'LinkSet',
+    'IdList',
+    'TranslationStack',
+    'TranslationSet',
+    'FieldList',
+    // Gene / Nucleotide / Protein
+    'Entrezgene',
+    'GBSeq',
+    'GBFeature',
+    'GBQualifier',
+    'GBReference',
+    'GBAuthor',
+    // GEO
+    'Series',
+    'Sample',
+    'Platform',
+    // SRA
+    'EXPERIMENT_PACKAGE',
+    'RUN',
+    // Taxonomy
+    'Taxon',
+    'LineageEx',
+]);
+/**
+ * Decode numeric HTML/XML character references: &#xHH; and &#DDD;
+ *
+ * fast-xml-parser decodes the standard 5 XML entities (& < > ' ")
+ * but does NOT decode numeric character references (ń β etc.).
+ * NCBI XML frequently uses these for accented characters in author names.
+ */
+function decodeHtmlEntities(text) {
+    return text.replace(/&#x([0-9a-fA-F]+);/g, (_m, hex) => String.fromCodePoint(parseInt(hex, 16))).replace(/&#(\d+);/g, (_m, dec) => String.fromCodePoint(parseInt(dec, 10)));
+}
+/**
+ * Inline markup tags that appear inside PubMed text fields.
+ * Stripped from raw XML before parsing to prevent text loss.
+ */
+const INLINE_TAG_RE = /<\/?(i|b|u|sup|sub|em|strong|italic|bold)(\s[^>]*)?\/?>/gi;
+const defaultParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    textNodeName: '#text',
+    isArray: (_name, _jPath, isLeafNode, isAttribute) => {
+        if (isAttribute)
+            return false;
+        // Extract the tag name from the jPath (last segment)
+        const tagName = _name;
+        return ARRAY_TAGS.has(tagName);
+    },
+    trimValues: true,
+    parseAttributeValue: true,
+    parseTagValue: true,
+    tagValueProcessor: (_tagName, tagValue) => {
+        if (typeof tagValue === 'string')
+            return decodeHtmlEntities(tagValue);
+        return tagValue;
+    },
+    attributeValueProcessor: (_attrName, attrValue) => {
+        if (typeof attrValue === 'string')
+            return decodeHtmlEntities(attrValue);
+        return attrValue;
+    },
+});
+/**
+ * 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 function parseXml(xml) {
+    // Strip inline formatting tags before parsing to prevent text loss.
+    // e.g. "The Role of<i>TP53</i>in cancer" → "The Role of TP53 in cancer"
+    const cleaned = xml.replace(INLINE_TAG_RE, '');
+    return defaultParser.parse(cleaned);
+}

package/dist/yaml-schema.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared YAML CLI definition types.
+ * Used by both discovery.ts (runtime) and build-manifest.ts (build-time).
+ *
+ * Also provides parseYamlCli() which converts a raw YAML object into a
+ * CliCommand and registers it via cli().
+ */
+import type { Arg } from './registry.js';
+export interface YamlArgDefinition {
+    type?: string;
+    default?: unknown;
+    required?: boolean;
+    positional?: boolean;
+    description?: string;
+    help?: string;
+    choices?: string[];
+}
+export interface YamlCliDefinition {
+    site?: string;
+    name?: string;
+    description?: string;
+    database?: string;
+    strategy?: string;
+    args?: Record<string, YamlArgDefinition>;
+    columns?: string[];
+    pipeline?: Record<string, unknown>[];
+    timeout?: number;
+    defaultFormat?: string;
+    aliases?: string[];
+}
+/** Convert YAML args definition to the internal Arg[] format. */
+export declare function parseYamlArgs(args: Record<string, YamlArgDefinition> | undefined): Arg[];
+/**
+ * Parse a raw YAML object into a CliCommand and register it.
+ *
+ * @param raw     Parsed YAML object (from js-yaml.load)
+ * @param source  File path or identifier for debugging
+ * @param defaultSite  Fallback site name if not specified in YAML (e.g. derived from directory name)
+ */
+export declare function parseYamlCli(raw: YamlCliDefinition, source: string, defaultSite?: string): void;

package/dist/yaml-schema.js

@@ -0,0 +1,62 @@
+/**
+ * Shared YAML CLI definition types.
+ * Used by both discovery.ts (runtime) and build-manifest.ts (build-time).
+ *
+ * Also provides parseYamlCli() which converts a raw YAML object into a
+ * CliCommand and registers it via cli().
+ */
+import { cli, Strategy } from './registry.js';
+// ── Arg normalizer ──────────────────────────────────────────────────────────
+/** Convert YAML args definition to the internal Arg[] format. */
+export function parseYamlArgs(args) {
+    if (!args || typeof args !== 'object')
+        return [];
+    const result = [];
+    for (const [argName, argDef] of Object.entries(args)) {
+        result.push({
+            name: argName,
+            type: argDef?.type ?? 'str',
+            default: argDef?.default,
+            required: argDef?.required ?? false,
+            positional: argDef?.positional ?? false,
+            help: argDef?.description ?? argDef?.help ?? '',
+            choices: argDef?.choices,
+        });
+    }
+    return result;
+}
+// ── YAML → CliCommand ───────────────────────────────────────────────────────
+function parseStrategy(rawStrategy) {
+    if (!rawStrategy)
+        return Strategy.PUBLIC;
+    const upper = rawStrategy.toUpperCase();
+    if (upper === 'API_KEY')
+        return Strategy.API_KEY;
+    return Strategy.PUBLIC;
+}
+/**
+ * Parse a raw YAML object into a CliCommand and register it.
+ *
+ * @param raw     Parsed YAML object (from js-yaml.load)
+ * @param source  File path or identifier for debugging
+ * @param defaultSite  Fallback site name if not specified in YAML (e.g. derived from directory name)
+ */
+export function parseYamlCli(raw, source, defaultSite) {
+    const site = raw.site ?? defaultSite ?? 'unknown';
+    const name = raw.name ?? source.replace(/\.(yaml|yml)$/, '').split('/').pop() ?? 'unnamed';
+    const strategy = parseStrategy(raw.strategy);
+    const args = parseYamlArgs(raw.args);
+    cli({
+        site,
+        name,
+        aliases: raw.aliases,
+        description: raw.description,
+        database: raw.database,
+        strategy,
+        args,
+        columns: raw.columns,
+        pipeline: raw.pipeline,
+        timeoutSeconds: raw.timeout,
+        defaultFormat: raw.defaultFormat,
+    });
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@yangfei_93sky/biocli",
+  "version": "0.2.0",
+  "description": "Query biological databases from the terminal — agent-first bioinformatics CLI",
+  "type": "module",
+  "main": "dist/main.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "biocli": "dist/main.js",
+    "ncbicli": "dist/main.js"
+  },
+  "exports": {
+    ".": "./dist/main.js",
+    "./registry": "./dist/registry-api.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/main.ts",
+    "build": "npm run clean-dist && tsc -p tsconfig.build.json && npm run clean-yaml && npm run copy-yaml && npm run build-manifest",
+    "build-manifest": "node dist/build-manifest.js",
+    "clean-dist": "node scripts/clean-dist.cjs",
+    "clean-yaml": "node scripts/clean-yaml.cjs",
+    "copy-yaml": "node scripts/copy-yaml.cjs",
+    "start": "node dist/main.js",
+    "postinstall": "node scripts/postinstall.cjs || true",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --project unit --passWithNoTests",
+    "test:adapter": "vitest run --project adapter --passWithNoTests",
+    "test:e2e": "vitest run --project e2e --passWithNoTests",
+    "test:smoke": "vitest run --project smoke --passWithNoTests",
+    "test:all": "vitest run --passWithNoTests",
+    "smoke:core": "bash scripts/smoke-core.sh",
+    "smoke:live": "bash scripts/smoke-live.sh"
+  },
+  "keywords": [
+    "ncbi",
+    "pubmed",
+    "bioinformatics",
+    "cli",
+    "gene",
+    "geo",
+    "sra"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "fast-xml-parser": "^4.5.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.0"
+  }
+}