@yeyuan98/opencode-bioresearcher-plugin 1.4.1 → 1.5.0

package/dist/db-tools/pool.js

@@ -0,0 +1,49 @@
+import * as mysql from 'mysql2/promise';
+let pool = null;
+let currentConfig = null;
+function createPoolConfig(config) {
+    return {
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        charset: config.charset,
+        connectTimeout: config.connectionTimeout,
+        waitForConnections: true,
+        connectionLimit: 10,
+        queueLimit: 0,
+        namedPlaceholders: true,
+    };
+}
+export function getPool(config) {
+    if (pool && currentConfig && isSameConfig(currentConfig, config)) {
+        return pool;
+    }
+    if (pool) {
+        pool.end().catch(err => console.error('[db-tools] Previous pool cleanup failed:', err.message));
+    }
+    pool = mysql.createPool(createPoolConfig(config));
+    currentConfig = config;
+    return pool;
+}
+function isSameConfig(a, b) {
+    return (a.host === b.host &&
+        a.port === b.port &&
+        a.user === b.user &&
+        a.password === b.password &&
+        a.database === b.database);
+}
+export async function closePool() {
+    if (pool) {
+        await pool.end().catch(err => console.error('[db-tools] Pool close failed:', err.message));
+        pool = null;
+        currentConfig = null;
+    }
+}
+export function getPoolStatus() {
+    return {
+        initialized: pool !== null,
+        hasConfig: currentConfig !== null,
+    };
+}

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

@@ -0,0 +1,27 @@
+import { ToolContext } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+export declare const dbQuery: {
+    description: string;
+    args: {
+        sql: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    };
+    execute(args: {
+        sql: string;
+        params?: Record<string, any> | undefined;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const dbListTables: {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<string>;
+};
+export declare const dbDescribeTable: {
+    description: string;
+    args: {
+        table_name: z.ZodString;
+    };
+    execute(args: {
+        table_name: string;
+    }, context: ToolContext): Promise<string>;
+};

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

@@ -0,0 +1,191 @@
+import { tool } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+import { initializeBackend, getDefaultBackend } from '../backends';
+import { validateReadOnlyQuery, validateCollectionName } from '../core/validator';
+import { getConfigFromEnv } from '../core/base';
+async function ensureBackend() {
+    let backend = getDefaultBackend();
+    if (!backend) {
+        const config = getConfigFromEnv();
+        backend = await initializeBackend(config);
+    }
+    return backend;
+}
+export const dbQuery = tool({
+    description: `Execute a SELECT query on the database with named parameters.
+
+**Examples:**
+- Simple query: \`SELECT * FROM users LIMIT 10\`
+- With named params: \`SELECT * FROM users WHERE status = :status AND created_at > :date\`
+- Join query: \`SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id\`
+- MongoDB query: \`SELECT * FROM users WHERE status = 'active' LIMIT 10\`
+
+**Parameters:**
+- Use named placeholders like \`:paramName\` for parameters
+- Pass parameter values in the \`params\` object: \`{ "status": "active", "date": "2024-01-01" }\`
+
+**Note:** Only SELECT statements are allowed (read-only access).
+
+**Backend Support:**
+- MySQL: Native SQL execution
+- MongoDB: SQL is translated to MongoDB queries automatically`,
+    args: {
+        sql: z.string().describe('SELECT SQL query to execute. Use named placeholders like :name for parameters.'),
+        params: z.record(z.string(), z.any()).optional().describe('Named parameters as key-value pairs (e.g., { "status": "active", "limit": 10 })'),
+    },
+    execute: async (args, _context) => {
+        try {
+            const backend = await ensureBackend();
+            const validation = validateReadOnlyQuery(args.sql, backend.type);
+            if (!validation.valid && validation.error) {
+                return JSON.stringify(validation.error, null, 2);
+            }
+            const result = await backend.executeQuery({
+                sql: args.sql,
+                params: args.params,
+            });
+            return JSON.stringify(result, null, 2);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'BACKEND_ERROR',
+                    message: errorMessage,
+                },
+                metadata: { executionTimeMs: 0, backend: 'unknown' },
+            }, null, 2);
+        }
+    },
+});
+export const dbListTables = tool({
+    description: `List all tables/collections in the current database with metadata.
+
+**Returns:**
+- Table/collection names and types (TABLE, VIEW, COLLECTION, etc.)
+- For MySQL: Storage engine (InnoDB, MyISAM, etc.), row count, creation time
+- For MongoDB: Collection type information
+
+**Usage:** Call this first to discover what tables/collections are available before using dbDescribeTable or dbQuery.`,
+    args: {},
+    execute: async (_args, _context) => {
+        const startTime = Date.now();
+        try {
+            const backend = await ensureBackend();
+            const collections = await backend.listCollections();
+            const result = {
+                success: true,
+                data: {
+                    tables: collections,
+                    count: collections.length,
+                },
+                metadata: {
+                    executionTimeMs: Date.now() - startTime,
+                    backend: backend.type,
+                },
+            };
+            return JSON.stringify(result, null, 2);
+        }
+        catch (error) {
+            const backend = getDefaultBackend();
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'LIST_TABLES_ERROR',
+                    message: errorMessage,
+                    hints: [
+                        'Check that the database server is running',
+                        'Verify your database credentials',
+                    ],
+                },
+                metadata: {
+                    executionTimeMs: Date.now() - startTime,
+                    backend: backend?.type || 'unknown',
+                },
+            }, null, 2);
+        }
+    },
+});
+export const dbDescribeTable = tool({
+    description: `Get the column/field schema for a specific table/collection.
+
+**Returns for each column/field:**
+- Field name
+- Data type (VARCHAR, INT, TEXT, DATETIME, etc. for MySQL; BSON types for MongoDB)
+- Nullable status
+- Key type (PRI for primary key, etc.)
+- Default value
+- Extra info (auto_increment, etc.)
+- Comments/description
+
+**Workflow:**
+1. Use \`dbListTables\` first to see available tables/collections
+2. Use this tool to understand the column/field structure
+3. Use \`dbQuery\` to query the data`,
+    args: {
+        table_name: z.string().describe('Name of the table/collection to describe. Use dbListTables to see available names.'),
+    },
+    execute: async (args, _context) => {
+        const startTime = Date.now();
+        try {
+            const backend = await ensureBackend();
+            const validation = validateCollectionName(args.table_name, backend.type);
+            if (!validation.valid && validation.error) {
+                return JSON.stringify(validation.error, null, 2);
+            }
+            const columns = await backend.describeCollection(args.table_name);
+            if (!columns || columns.length === 0) {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'TABLE_NOT_FOUND',
+                        message: `Table/collection '${args.table_name}' not found in database`,
+                        hints: [
+                            'Use dbListTables to see available tables/collections',
+                            'Check the name for typos',
+                            'Make sure you are connected to the correct database',
+                        ],
+                    },
+                    metadata: {
+                        executionTimeMs: Date.now() - startTime,
+                        backend: backend.type,
+                    },
+                }, null, 2);
+            }
+            const result = {
+                success: true,
+                data: {
+                    table: args.table_name,
+                    columns,
+                    columnCount: columns.length,
+                },
+                metadata: {
+                    executionTimeMs: Date.now() - startTime,
+                    backend: backend.type,
+                },
+            };
+            return JSON.stringify(result, null, 2);
+        }
+        catch (error) {
+            const backend = getDefaultBackend();
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'DESCRIBE_TABLE_ERROR',
+                    message: errorMessage,
+                    hints: [
+                        'Use dbListTables to see available tables/collections',
+                        'Check the table name for typos',
+                    ],
+                },
+                metadata: {
+                    executionTimeMs: Date.now() - startTime,
+                    backend: backend?.type || 'unknown',
+                },
+            }, null, 2);
+        }
+    },
+});

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

@@ -0,0 +1,27 @@
+import { ToolContext } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+export declare const dbQuery: {
+    description: string;
+    args: {
+        sql: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    };
+    execute(args: {
+        sql: string;
+        params?: Record<string, any> | undefined;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const dbListTables: {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<string>;
+};
+export declare const dbDescribeTable: {
+    description: string;
+    args: {
+        table_name: z.ZodString;
+    };
+    execute(args: {
+        table_name: string;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/db-tools/tools.js

@@ -0,0 +1,111 @@
+import { tool } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+import { getDefaultBackend, initializeBackend } from './backends';
+import { getConfigFromEnv } from './core/base';
+import { validateReadOnlyQuery, validateCollectionName } from './core/validator';
+import { formatCollectionsResult, formatSchemaResult, formatCollectionNotFound, formatInitError } from './utils';
+async function getOrCreateBackend() {
+    let backend = getDefaultBackend();
+    if (!backend) {
+        const config = getConfigFromEnv();
+        backend = await initializeBackend(config);
+    }
+    return backend;
+}
+export const dbQuery = tool({
+    description: `Execute a SELECT query on the database with named parameters.
+
+**Examples:**
+- Simple query: \`SELECT * FROM users LIMIT 10\`
+- With named params: \`SELECT * FROM users WHERE status = :status AND created_at > :date\`
+- Join query: \`SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id\`
+
+**Parameters:**
+- Use named placeholders like \`:paramName\` for parameters
+- Pass parameter values in the \`params\` object: \`{ "status": "active", "date": "2024-01-01" }\`
+
+**Note:** Only SELECT statements are allowed (read-only access).`,
+    args: {
+        sql: z.string().describe('SELECT SQL query to execute. Use named placeholders like :name for parameters.'),
+        params: z.record(z.string(), z.any()).optional().describe('Named parameters as key-value pairs (e.g., { "status": "active", "limit": 10 })'),
+    },
+    execute: async (args, _context) => {
+        try {
+            const backend = await getOrCreateBackend();
+            const validation = validateReadOnlyQuery(args.sql, backend.type);
+            if (!validation.valid && validation.error) {
+                return JSON.stringify(validation.error, null, 2);
+            }
+            const result = await backend.executeQuery({
+                sql: args.sql,
+                params: args.params,
+            });
+            return JSON.stringify(result, null, 2);
+        }
+        catch (error) {
+            return JSON.stringify(formatInitError(error), null, 2);
+        }
+    },
+});
+export const dbListTables = tool({
+    description: `List all tables/collections in the current database with metadata.
+
+**Returns:**
+- Table/collection names and types (TABLE, VIEW, COLLECTION)
+- Storage engine (InnoDB, MyISAM, etc.) for MySQL
+- Approximate row count
+- Creation time (MySQL only)
+- Table comments
+
+**Usage:** Call this first to discover what tables are available before using dbDescribeTable or dbQuery.`,
+    args: {},
+    execute: async (_args, _context) => {
+        try {
+            const backend = await getOrCreateBackend();
+            const collections = await backend.listCollections();
+            const result = formatCollectionsResult(collections, 0, backend.type);
+            return JSON.stringify(result, null, 2);
+        }
+        catch (error) {
+            return JSON.stringify(formatInitError(error), null, 2);
+        }
+    },
+});
+export const dbDescribeTable = tool({
+    description: `Get the column schema for a specific table/collection.
+
+**Returns for each column/field:**
+- Field name
+- Data type (VARCHAR, INT, TEXT, DATETIME, etc.)
+- Nullable status
+- Key type (PRI for primary key, UNI for unique, MUL for multiple)
+- Default value
+- Extra info (auto_increment, etc.)
+- Column comments
+
+**Workflow:**
+1. Use \`dbListTables\` first to see available tables/collections
+2. Use this tool to understand the column/field structure
+3. Use \`dbQuery\` to query the data`,
+    args: {
+        table_name: z.string().describe('Name of the table/collection to describe. Use dbListTables to see available tables.'),
+    },
+    execute: async (args, _context) => {
+        try {
+            const backend = await getOrCreateBackend();
+            const validation = validateCollectionName(args.table_name, backend.type);
+            if (!validation.valid && validation.error) {
+                return JSON.stringify(validation.error, null, 2);
+            }
+            const columns = await backend.describeCollection(args.table_name);
+            if (columns.length === 0) {
+                return JSON.stringify(formatCollectionNotFound(args.table_name, backend.type), null, 2);
+            }
+            const result = formatSchemaResult(columns, args.table_name, 0, backend.type);
+            return JSON.stringify(result, null, 2);
+        }
+        catch (error) {
+            return JSON.stringify(formatInitError(error), null, 2);
+        }
+    },
+});

package/dist/db-tools/types.d.ts

@@ -0,0 +1,94 @@
+import type { RowDataPacket } from 'mysql2/promise';
+export interface DbConfig {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    charset?: string;
+    connectionTimeout?: number;
+}
+export interface QueryOptions {
+    sql: string;
+    params?: Record<string, unknown> | unknown[];
+}
+export interface FieldInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+    key: string | null;
+    default: unknown;
+    extra: string | null;
+}
+export interface StructuredError {
+    code: string;
+    message: string;
+    details?: string;
+    hints?: string[];
+}
+export interface ToolResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: StructuredError;
+    metadata?: {
+        executionTimeMs: number;
+        [key: string]: unknown;
+    };
+}
+export interface QueryResultData {
+    rows: RowDataPacket[];
+    rowCount: number;
+    fields: FieldInfo[];
+}
+export interface QueryResult extends ToolResponse<QueryResultData> {
+    success: true;
+    data: QueryResultData;
+}
+export interface QueryError extends ToolResponse<never> {
+    success: false;
+    error: StructuredError;
+}
+export type QueryResponse = QueryResult | QueryError;
+export interface TableInfo {
+    tableName: string;
+    tableType: string;
+    engine: string | null;
+    rowCount: number | null;
+    createdAt: string | null;
+    comment: string | null;
+}
+export interface TablesResultData {
+    tables: TableInfo[];
+    count: number;
+}
+export interface ColumnSchema {
+    field: string;
+    type: string;
+    nullable: boolean;
+    key: string | null;
+    defaultValue: unknown;
+    extra: string | null;
+    comment: string | null;
+}
+export interface SchemaResultData {
+    table: string;
+    columns: ColumnSchema[];
+    columnCount: number;
+}
+export type MySQLError = Error & {
+    code?: string;
+    errno?: number;
+    sql?: string;
+    sqlState?: string;
+};
+export declare const DEFAULT_CONFIG: Partial<DbConfig>;
+export declare const ERROR_HINTS: {
+    readonly CONNECTION: readonly ["Check that the database server is running", "Verify DB_HOST and DB_PORT environment variables", "Ensure network connectivity to the database"];
+    readonly AUTH: readonly ["Verify DB_USER and DB_PASSWORD environment variables", "Check that the user has permissions for the database"];
+    readonly UNKNOWN_TABLE: readonly ["Use dbListTables to see available tables", "Check the table name for typos"];
+    readonly UNKNOWN_COLUMN: readonly ["Use dbDescribeTable to see available columns", "Check the column name for typos"];
+    readonly SYNTAX: readonly ["Check your SQL syntax", "Ensure all identifiers are properly quoted if needed"];
+    readonly GENERIC: readonly ["Check your query syntax", "Use dbListTables to see available tables", "Use dbDescribeTable to check column names"];
+};
+export declare function isQueryResult(response: QueryResponse): response is QueryResult;
+export declare function isQueryError(response: QueryResponse): response is QueryError;

package/dist/db-tools/types.js

@@ -0,0 +1,40 @@
+export const DEFAULT_CONFIG = {
+    host: 'localhost',
+    port: 3306,
+    charset: 'utf8mb4',
+    connectionTimeout: 10000,
+};
+export const ERROR_HINTS = {
+    CONNECTION: [
+        'Check that the database server is running',
+        'Verify DB_HOST and DB_PORT environment variables',
+        'Ensure network connectivity to the database',
+    ],
+    AUTH: [
+        'Verify DB_USER and DB_PASSWORD environment variables',
+        'Check that the user has permissions for the database',
+    ],
+    UNKNOWN_TABLE: [
+        'Use dbListTables to see available tables',
+        'Check the table name for typos',
+    ],
+    UNKNOWN_COLUMN: [
+        'Use dbDescribeTable to see available columns',
+        'Check the column name for typos',
+    ],
+    SYNTAX: [
+        'Check your SQL syntax',
+        'Ensure all identifiers are properly quoted if needed',
+    ],
+    GENERIC: [
+        'Check your query syntax',
+        'Use dbListTables to see available tables',
+        'Use dbDescribeTable to check column names',
+    ],
+};
+export function isQueryResult(response) {
+    return response.success === true;
+}
+export function isQueryError(response) {
+    return response.success === false;
+}

package/dist/db-tools/utils.d.ts

@@ -0,0 +1,33 @@
+import type { IQueryResult, ICollectionInfo, IColumnSchema } from './interface';
+export declare function formatCollectionsResult(collections: ICollectionInfo[], executionTimeMs: number, backendType: string): {
+    success: boolean;
+    data: {
+        tables: {
+            tableName: string;
+            tableType: "table" | "view" | "collection";
+            engine: string | null;
+            rowCount: number | null;
+            createdAt: string | null;
+            comment: string | null;
+        }[];
+        count: number;
+    };
+    metadata: {
+        executionTimeMs: number;
+        backend: string;
+    };
+};
+export declare function formatSchemaResult(columns: IColumnSchema[], tableName: string, executionTimeMs: number, backendType: string): {
+    success: boolean;
+    data: {
+        table: string;
+        columns: IColumnSchema[];
+        columnCount: number;
+    };
+    metadata: {
+        executionTimeMs: number;
+        backend: string;
+    };
+};
+export declare function formatCollectionNotFound(tableName: string, backendType: string): IQueryResult;
+export declare function formatInitError(error: unknown, backendType?: string): IQueryResult;

package/dist/db-tools/utils.js

@@ -0,0 +1,94 @@
+import { ERROR_HINTS, getErrorHints } from './core/validator';
+export function formatCollectionsResult(collections, executionTimeMs, backendType) {
+    return {
+        success: true,
+        data: {
+            tables: collections.map(c => ({
+                tableName: c.name,
+                tableType: c.type,
+                engine: c.engine ?? null,
+                rowCount: c.rowCount ?? null,
+                createdAt: c.createdAt ?? null,
+                comment: c.comment ?? null,
+            })),
+            count: collections.length,
+        },
+        metadata: { executionTimeMs, backend: backendType },
+    };
+}
+export function formatSchemaResult(columns, tableName, executionTimeMs, backendType) {
+    return {
+        success: true,
+        data: {
+            table: tableName,
+            columns,
+            columnCount: columns.length,
+        },
+        metadata: { executionTimeMs, backend: backendType },
+    };
+}
+export function formatCollectionNotFound(tableName, backendType) {
+    return {
+        success: false,
+        error: {
+            code: 'COLLECTION_NOT_FOUND',
+            message: `Collection/table '${tableName}' not found`,
+            hints: [
+                'Use dbListTables to see available collections/tables',
+                'Check the name for typos',
+                'Make sure you are connected to the correct database',
+            ],
+        },
+        metadata: { executionTimeMs: 0, backend: backendType },
+    };
+}
+export function formatInitError(error, backendType = 'unknown') {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const errorCode = err.code || 'INIT_ERROR';
+    const hints = getInitErrorHints(errorCode, backendType);
+    return {
+        success: false,
+        error: {
+            code: errorCode,
+            message: `Database initialization failed: ${err.message}`,
+            hints,
+        },
+        metadata: { executionTimeMs: 0, backend: backendType },
+    };
+}
+function getInitErrorHints(code, backendType) {
+    const codeStr = String(code || '');
+    if (backendType === 'mongodb' || codeStr.includes('Mongo')) {
+        const mongoHints = {
+            'MongoNetworkError': [
+                'MongoDB network error - check connection string',
+                'For Atlas: verify IP whitelist in Atlas dashboard',
+                'Check MONGODB_URI format: mongodb+srv://user:pass@cluster/db',
+            ],
+            'MongoServerError': [
+                'MongoDB authentication failed',
+                'Check credentials in MONGODB_URI',
+                'Verify authSource if using custom auth database',
+            ],
+            'ECONNREFUSED': [
+                'MongoDB server is not running or not reachable',
+                'Check DB_HOST and DB_PORT environment variables',
+                'For local: ensure mongod is running',
+            ],
+        };
+        return mongoHints[code] || [...ERROR_HINTS.CONNECTION];
+    }
+    const mysqlHints = {
+        'ECONNREFUSED': [
+            'MySQL server is not running or not reachable',
+            'Check DB_HOST and DB_PORT environment variables',
+            'For Docker: ensure container is running and port is mapped',
+        ],
+        'ER_ACCESS_DENIED_ERROR': [
+            'MySQL authentication failed',
+            'Check DB_USER and DB_PASSWORD environment variables',
+            'Verify user has permissions for the database',
+        ],
+    };
+    return mysqlHints[code] || [...getErrorHints(code)];
+}