@yeyuan98/opencode-bioresearcher-plugin 1.4.0 → 1.5.0-alpha.0

package/README.md

@@ -77,19 +77,33 @@ Download pubmed article data from https://ftp.ncbi.nlm.nih.gov/pubmed/updatefile
 
 Reference: [PubMed Download Data](https://pubmed.ncbi.nlm.nih.gov/download/).
 
-### JSON Tools
-
-Extract, validate, and infer JSON schemas from data.
-
-**Robust JSON handling for LLM workflows.**
-
-```text
-Extract JSON from output.md using jsonExtract tool.
-Validate data.json against schema.json using jsonValidate tool.
-Infer schema from sample.json using jsonInfer tool.
-```
-
-## Skills
+### JSON Tools
+
+Extract, validate, and infer JSON schemas from data.
+
+**Robust JSON handling for LLM workflows.**
+
+```text
+Extract JSON from output.md using jsonExtract tool.
+Validate data.json against schema.json using jsonValidate tool.
+Infer schema from sample.json using jsonInfer tool.
+```
+
+### Database Tools
+
+Query MySQL and MongoDB databases with read-only access.
+
+**Explore your data warehouse without leaving the conversation.**
+
+```text
+List all tables in the database.
+Describe the schema for table users.
+Query orders placed in the last 30 days.
+```
+
+Configuration via `env.jsonc` in working directory. Use the `env-jsonc-setup` skill for guided setup.
+
+## Skills
 
 Skills are reusable prompt templates discovered from multiple paths:
 
@@ -104,13 +118,14 @@ This plugin provides a skill tool that overrides Opencode's built-in to support
 
 See [skill-tools/README.md](skill-tools/README.md) for full documentation.
 
-### Supplied skills
-
-- `demo-skill`: showcase skill tool mechanisms.
-- `python-setup-uv`: setup python runtime in your working directory with uv.
-- `pubmed-weekly`: automated download of pubmed daily update files over the past one week.
-- `long-table-summary`: batch-process large tables using parallel subagents for summarization.
-- `bioresearcher-core`: core patterns and utilities (retry, JSON tools, subagent waves) for skill development.
+### Supplied skills
+
+- `demo-skill`: showcase skill tool mechanisms.
+- `python-setup-uv`: setup python runtime in your working directory with uv.
+- `pubmed-weekly`: automated download of pubmed daily update files over the past one week.
+- `long-table-summary`: batch-process large tables using parallel subagents for summarization.
+- `bioresearcher-core`: core patterns and utilities (retry, JSON tools, subagent waves) for skill development.
+- `env-jsonc-setup`: guided setup for database connection configuration (db-tools).
 
 Prompt the following and follow along:
 

package/dist/db-tools/backends/index.d.ts

@@ -0,0 +1,11 @@
+import type { IDatabaseBackend, IConnectionConfig, BackendType } from '../interface';
+type BackendFactory = (config: IConnectionConfig) => IDatabaseBackend;
+export declare function registerBackend(type: BackendType, factory: BackendFactory): void;
+export declare function createBackend(config: IConnectionConfig): IDatabaseBackend;
+export declare function getSupportedTypes(): BackendType[];
+export declare function isBackendSupported(type: string): type is BackendType;
+export declare function getBackend(config?: IConnectionConfig): IDatabaseBackend;
+export declare function initializeBackend(config: IConnectionConfig): Promise<IDatabaseBackend>;
+export declare function closeBackend(): Promise<void>;
+export declare function getDefaultBackend(): IDatabaseBackend | null;
+export {};

package/dist/db-tools/backends/index.js

@@ -0,0 +1,48 @@
+import { MySQLBackend } from './mysql';
+import { MongoDBBackend } from './mongodb';
+const backendRegistry = new Map();
+export function registerBackend(type, factory) {
+    backendRegistry.set(type, factory);
+}
+export function createBackend(config) {
+    const factory = backendRegistry.get(config.type);
+    if (!factory) {
+        throw new Error(`Unsupported backend type: ${config.type}. Supported types: ${getSupportedTypes().join(', ')}`);
+    }
+    return factory(config);
+}
+export function getSupportedTypes() {
+    return Array.from(backendRegistry.keys());
+}
+export function isBackendSupported(type) {
+    return backendRegistry.has(type);
+}
+registerBackend('mysql', (config) => new MySQLBackend(config));
+registerBackend('mongodb', (config) => new MongoDBBackend(config));
+let defaultBackend = null;
+export function getBackend(config) {
+    if (!config) {
+        if (!defaultBackend) {
+            throw new Error('No backend initialized. Call initializeBackend() first or provide config.');
+        }
+        return defaultBackend;
+    }
+    return createBackend(config);
+}
+export async function initializeBackend(config) {
+    if (defaultBackend) {
+        await defaultBackend.disconnect();
+    }
+    defaultBackend = createBackend(config);
+    await defaultBackend.connect();
+    return defaultBackend;
+}
+export async function closeBackend() {
+    if (defaultBackend) {
+        await defaultBackend.disconnect();
+        defaultBackend = null;
+    }
+}
+export function getDefaultBackend() {
+    return defaultBackend;
+}

package/dist/db-tools/backends/mongodb/backend.d.ts

@@ -0,0 +1,15 @@
+import type { IConnectionConfig, IQuery, IQueryResult, ICollectionInfo, IColumnSchema, IConnectionPool } from '../../interface';
+import { BaseBackend } from '../../core/base';
+import { MongoDBConnectionConfig } from './connection';
+export declare class MongoDBBackend extends BaseBackend {
+    readonly type = "mongodb";
+    readonly config: MongoDBConnectionConfig;
+    constructor(config: IConnectionConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getPool(): IConnectionPool | null;
+    executeQuery(query: IQuery): Promise<IQueryResult>;
+    listCollections(): Promise<ICollectionInfo[]>;
+    describeCollection(name: string): Promise<IColumnSchema[]>;
+}
+export declare function createMongoDBBackend(config: IConnectionConfig): MongoDBBackend;

package/dist/db-tools/backends/mongodb/backend.js

@@ -0,0 +1,76 @@
+import { BaseBackend } from '../../core/base';
+import { getDb, closeClient, validateMongoDBConfig, MongoDBConnectionPool, } from './connection';
+import { parseSelectQuery, executeParsedQuery, listMongoDBCollections, describeMongoDBCollection, createFieldInfoFromRow, SQLParseError, } from './translator';
+export class MongoDBBackend extends BaseBackend {
+    type = 'mongodb';
+    config;
+    constructor(config) {
+        super();
+        this.config = {
+            ...config,
+            uri: config.options?.uri,
+            authSource: config.options?.authSource,
+            replicaSet: config.options?.replicaSet,
+        };
+    }
+    async connect() {
+        validateMongoDBConfig(this.config);
+        await getDb(this.config);
+        this._connected = true;
+    }
+    async disconnect() {
+        await closeClient();
+        this._connected = false;
+    }
+    getPool() {
+        return new MongoDBConnectionPool(this.config);
+    }
+    async executeQuery(query) {
+        const startTime = Date.now();
+        try {
+            if (!this._connected) {
+                await this.connect();
+            }
+            const db = await getDb(this.config);
+            const parsed = parseSelectQuery(query.sql);
+            const collection = db.collection(parsed.collection);
+            const rows = await executeParsedQuery(collection, parsed, query.params);
+            const fields = createFieldInfoFromRow(rows[0] || {});
+            const executionTimeMs = Date.now() - startTime;
+            return this.createSuccessResult(rows, fields, executionTimeMs);
+        }
+        catch (error) {
+            const executionTimeMs = Date.now() - startTime;
+            if (error instanceof SQLParseError) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'SQL_PARSE_ERROR',
+                        message: error.message,
+                        hints: [
+                            'Check your SQL syntax',
+                            'Only SELECT queries are supported',
+                            'Supported clauses: WHERE, ORDER BY, LIMIT, OFFSET, GROUP BY, HAVING',
+                        ],
+                    },
+                    metadata: {
+                        executionTimeMs,
+                        backend: this.type,
+                    },
+                };
+            }
+            return this.createErrorResult(error, executionTimeMs);
+        }
+    }
+    async listCollections() {
+        const db = await getDb(this.config);
+        return listMongoDBCollections(db);
+    }
+    async describeCollection(name) {
+        const db = await getDb(this.config);
+        return describeMongoDBCollection(db, name);
+    }
+}
+export function createMongoDBBackend(config) {
+    return new MongoDBBackend(config);
+}

package/dist/db-tools/backends/mongodb/connection.d.ts

@@ -0,0 +1,27 @@
+import { MongoClient, MongoClientOptions, Db } from 'mongodb';
+import type { IConnectionConfig, IConnectionPool, IConnection } from '../../interface';
+export interface MongoDBConnectionConfig extends IConnectionConfig {
+    uri?: string;
+    authSource?: string;
+    replicaSet?: string;
+}
+declare let client: MongoClient | null;
+declare let db: Db | null;
+export declare function buildConnectionString(config: MongoDBConnectionConfig): string;
+export declare function createClientOptions(config: MongoDBConnectionConfig): MongoClientOptions;
+export declare function getClient(config: MongoDBConnectionConfig): Promise<MongoClient>;
+export declare function getDb(config: MongoDBConnectionConfig): Promise<Db>;
+export declare function closeClient(): Promise<void>;
+export declare function getClientStatus(): {
+    initialized: boolean;
+    hasConfig: boolean;
+};
+export declare function validateMongoDBConfig(config: MongoDBConnectionConfig): void;
+export declare class MongoDBConnectionPool implements IConnectionPool {
+    private config;
+    constructor(config: MongoDBConnectionConfig);
+    getConnection(): Promise<IConnection>;
+    end(): Promise<void>;
+    isHealthy(): boolean;
+}
+export { client as _internalClient, db as _internalDb };

package/dist/db-tools/backends/mongodb/connection.js

@@ -0,0 +1,107 @@
+import { MongoClient } from 'mongodb';
+let client = null;
+let db = null;
+let currentConfig = null;
+export function buildConnectionString(config) {
+    if (config.uri) {
+        return config.uri;
+    }
+    const auth = config.username && config.password
+        ? `${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@`
+        : '';
+    const host = config.host || 'localhost';
+    const port = config.port || 27017;
+    const database = config.database || 'test';
+    let uri = `mongodb://${auth}${host}:${port}/${database}`;
+    const params = [];
+    if (config.authSource)
+        params.push(`authSource=${config.authSource}`);
+    if (config.replicaSet)
+        params.push(`replicaSet=${config.replicaSet}`);
+    if (params.length > 0) {
+        uri += '?' + params.join('&');
+    }
+    return uri;
+}
+export function createClientOptions(config) {
+    return {
+        connectTimeoutMS: config.connectionTimeout || 10000,
+        serverSelectionTimeoutMS: config.connectionTimeout || 10000,
+        maxPoolSize: 10,
+        minPoolSize: 1,
+    };
+}
+export async function getClient(config) {
+    if (client && currentConfig && isSameConfig(currentConfig, config)) {
+        return client;
+    }
+    if (client) {
+        await client.close().catch(err => console.error('[mongodb-backend] Previous client cleanup failed:', err.message));
+    }
+    const uri = buildConnectionString(config);
+    const options = createClientOptions(config);
+    client = new MongoClient(uri, options);
+    await client.connect();
+    db = client.db(config.database);
+    currentConfig = config;
+    return client;
+}
+export async function getDb(config) {
+    if (db && currentConfig && isSameConfig(currentConfig, config)) {
+        return db;
+    }
+    await getClient(config);
+    return db;
+}
+function isSameConfig(a, b) {
+    if (a.uri && b.uri) {
+        return a.uri === b.uri;
+    }
+    return (a.host === b.host &&
+        a.port === b.port &&
+        a.username === b.username &&
+        a.password === b.password &&
+        a.database === b.database);
+}
+export async function closeClient() {
+    if (client) {
+        await client.close().catch(err => console.error('[mongodb-backend] Client close failed:', err.message));
+        client = null;
+        db = null;
+        currentConfig = null;
+    }
+}
+export function getClientStatus() {
+    return {
+        initialized: client !== null,
+        hasConfig: currentConfig !== null,
+    };
+}
+export function validateMongoDBConfig(config) {
+    if (!config.uri && !config.database) {
+        throw new Error(`Missing required MongoDB configuration.\n` +
+            `Provide either:\n` +
+            `  - MONGODB_URI environment variable (for Atlas or connection strings)\n` +
+            `  - DB_DATABASE environment variable (for local MongoDB)`);
+    }
+}
+export class MongoDBConnectionPool {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async getConnection() {
+        const client = await getClient(this.config);
+        return {
+            isConnected: () => true,
+            close: async () => { },
+        };
+    }
+    async end() {
+        await closeClient();
+    }
+    isHealthy() {
+        return client !== null;
+    }
+}
+export { client as _internalClient, db as _internalDb };

package/dist/db-tools/backends/mongodb/index.d.ts

@@ -0,0 +1,4 @@
+export { MongoDBBackend, createMongoDBBackend } from './backend';
+export { getDb, closeClient, validateMongoDBConfig } from './connection';
+export type { MongoDBConnectionConfig } from './connection';
+export { parseSelectQuery, SQLParseError } from './translator';

package/dist/db-tools/backends/mongodb/index.js

@@ -0,0 +1,3 @@
+export { MongoDBBackend, createMongoDBBackend } from './backend';
+export { getDb, closeClient, validateMongoDBConfig } from './connection';
+export { parseSelectQuery, SQLParseError } from './translator';

package/dist/db-tools/backends/mongodb/translator.d.ts

@@ -0,0 +1,30 @@
+import type { Document, Collection, SortDirection } from 'mongodb';
+import type { IFieldInfo, IColumnSchema, ICollectionInfo, IRow } from '../../interface';
+type MutableSort = {
+    [key: string]: SortDirection;
+};
+export interface ParsedSelectQuery {
+    collection: string;
+    fields: string[] | null;
+    where: Record<string, unknown> | null;
+    orderBy: MutableSort | null;
+    limit: number | null;
+    offset: number | null;
+    groupBy: string[] | null;
+    having: Record<string, unknown> | null;
+    aggregations: AggregationFunction[] | null;
+}
+export interface AggregationFunction {
+    type: 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';
+    field: string;
+    alias?: string;
+}
+export declare class SQLParseError extends Error {
+    constructor(message: string);
+}
+export declare function parseSelectQuery(sql: string): ParsedSelectQuery;
+export declare function executeParsedQuery<T extends Document>(collection: Collection<T>, parsed: ParsedSelectQuery, params?: Record<string, unknown> | unknown[]): Promise<IRow[]>;
+export declare function listMongoDBCollections(db: import('mongodb').Db): Promise<ICollectionInfo[]>;
+export declare function describeMongoDBCollection(db: import('mongodb').Db, collectionName: string): Promise<IColumnSchema[]>;
+export declare function createFieldInfoFromRow(row: IRow): IFieldInfo[];
+export {};