@yeyuan98/opencode-bioresearcher-plugin 1.3.1 → 1.4.0

package/README.md

@@ -77,6 +77,18 @@ 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
 
 Skills are reusable prompt templates discovered from multiple paths:
@@ -97,6 +109,8 @@ See [skill-tools/README.md](skill-tools/README.md) for full documentation.
 - `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.
 
 Prompt the following and follow along:
 

package/dist/index.js

@@ -2,7 +2,7 @@ import { createBioResearcherAgent } from "./agents/bioresearcher/index";
 import { createBioResearcherDRAgent } from "./agents/bioresearcherDR/index";
 import { createBioResearcherDRWorkerAgent } from "./agents/bioresearcherDR_worker/index";
 import { tableTools } from "./table-tools/index";
-import { blockingTimer, calculator } from "./misc-tools/index";
+import { blockingTimer, calculator, jsonExtract, jsonValidate, jsonInfer } from "./misc-tools/index";
 import { parse_pubmed_articleSet } from "./parser-tools/pubmed";
 import { SkillTool } from "./skill-tools";
 export const BioResearcherPlugin = async () => {
@@ -18,6 +18,9 @@ export const BioResearcherPlugin = async () => {
             ...tableTools,
             blockingTimer,
             calculator,
+            jsonExtract,
+            jsonValidate,
+            jsonInfer,
             parse_pubmed_articleSet
         }
     };

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

@@ -1,2 +1,5 @@
 export { blockingTimer } from './timer';
 export { calculator } from './calculator';
+export { jsonExtract } from './json-extract';
+export { jsonValidate } from './json-validate';
+export { jsonInfer } from './json-infer';

package/dist/misc-tools/index.js

@@ -1,2 +1,5 @@
 export { blockingTimer } from './timer';
 export { calculator } from './calculator';
+export { jsonExtract } from './json-extract';
+export { jsonValidate } from './json-validate';
+export { jsonInfer } from './json-infer';

package/dist/misc-tools/json-extract.d.ts

@@ -0,0 +1,13 @@
+import { ToolContext } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+export declare const jsonExtract: {
+    description: string;
+    args: {
+        file_path: z.ZodString;
+        return_all: z.ZodDefault<z.ZodBoolean>;
+    };
+    execute(args: {
+        file_path: string;
+        return_all: boolean;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/misc-tools/json-extract.js

@@ -0,0 +1,394 @@
+import { tool } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+const MAX_FILE_SIZE = 200 * 1024 * 1024;
+const BINARY_EXTENSIONS = [
+    '.bin', '.exe', '.dll', '.so', '.dylib',
+    '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico',
+    '.pdf', '.zip', '.tar', '.gz', '.rar',
+    '.mp3', '.mp4', '.avi', '.mov', '.wav'
+];
+function findMatchingBrace(content, startIdx) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = startIdx; i < content.length; i++) {
+        const char = content[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (char === '\\') {
+            escape = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (!inString) {
+            if (char === '{')
+                depth++;
+            if (char === '}') {
+                depth--;
+                if (depth === 0)
+                    return i;
+            }
+        }
+    }
+    return -1;
+}
+function findMatchingBracket(content, startIdx) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = startIdx; i < content.length; i++) {
+        const char = content[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (char === '\\') {
+            escape = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (!inString) {
+            if (char === '[')
+                depth++;
+            if (char === ']') {
+                depth--;
+                if (depth === 0)
+                    return i;
+            }
+        }
+    }
+    return -1;
+}
+function isPathWithinDirectory(filePath, directory) {
+    const normalizedPath = path.normalize(path.resolve(filePath));
+    const normalizedDir = path.normalize(path.resolve(directory));
+    return normalizedPath.startsWith(normalizedDir + path.sep) ||
+        normalizedPath === normalizedDir;
+}
+function extractJsonFromContent(content) {
+    const trimmed = content.trim();
+    if (trimmed.length === 0) {
+        return { success: false, error: 'EMPTY_FILE' };
+    }
+    const jsonBlockMatch = trimmed.match(/```json\s*([\s\S]*?)\s*```/i);
+    if (jsonBlockMatch) {
+        try {
+            const jsonStr = jsonBlockMatch[1].trim();
+            const parsed = JSON.parse(jsonStr);
+            return {
+                success: true,
+                data: parsed,
+                method: 'json_code_block',
+                dataType: Array.isArray(parsed) ? 'array' : 'object'
+            };
+        }
+        catch { }
+    }
+    const codeBlockMatch = trimmed.match(/```\s*([\s\S]*?)\s*```/i);
+    if (codeBlockMatch) {
+        try {
+            const jsonStr = codeBlockMatch[1].trim();
+            const parsed = JSON.parse(jsonStr);
+            return {
+                success: true,
+                data: parsed,
+                method: 'code_block',
+                dataType: Array.isArray(parsed) ? 'array' : 'object'
+            };
+        }
+        catch { }
+    }
+    const jsonStart = trimmed.indexOf('{');
+    if (jsonStart !== -1) {
+        const jsonEnd = findMatchingBrace(trimmed, jsonStart);
+        if (jsonEnd !== -1 && jsonEnd > jsonStart) {
+            try {
+                const jsonStr = trimmed.slice(jsonStart, jsonEnd + 1);
+                const parsed = JSON.parse(jsonStr);
+                return {
+                    success: true,
+                    data: parsed,
+                    method: 'object',
+                    dataType: 'object'
+                };
+            }
+            catch { }
+        }
+    }
+    const arrStart = trimmed.indexOf('[');
+    if (arrStart !== -1) {
+        const arrEnd = findMatchingBracket(trimmed, arrStart);
+        if (arrEnd !== -1 && arrEnd > arrStart) {
+            try {
+                const jsonStr = trimmed.slice(arrStart, arrEnd + 1);
+                const parsed = JSON.parse(jsonStr);
+                return {
+                    success: true,
+                    data: parsed,
+                    method: 'array',
+                    dataType: 'array'
+                };
+            }
+            catch { }
+        }
+    }
+    return { success: false, error: 'NO_JSON_FOUND' };
+}
+function extractAllJsonFromContent(content) {
+    const trimmed = content.trim();
+    if (trimmed.length === 0) {
+        return { success: false, error: 'EMPTY_FILE' };
+    }
+    const extractedObjects = [];
+    let method = undefined;
+    const jsonBlockRegex = /```json\s*([\s\S]*?)\s*```/gi;
+    let match;
+    while ((match = jsonBlockRegex.exec(trimmed)) !== null) {
+        try {
+            const jsonStr = match[1].trim();
+            const parsed = JSON.parse(jsonStr);
+            extractedObjects.push(parsed);
+            method = 'json_code_block';
+        }
+        catch { }
+    }
+    if (extractedObjects.length > 0) {
+        return {
+            success: true,
+            data: extractedObjects,
+            method: method,
+            dataType: 'mixed',
+            count: extractedObjects.length
+        };
+    }
+    const codeBlockRegex = /```\s*([\s\S]*?)\s*```/gi;
+    while ((match = codeBlockRegex.exec(trimmed)) !== null) {
+        try {
+            const jsonStr = match[1].trim();
+            const parsed = JSON.parse(jsonStr);
+            extractedObjects.push(parsed);
+            method = 'code_block';
+        }
+        catch { }
+    }
+    if (extractedObjects.length > 0) {
+        return {
+            success: true,
+            data: extractedObjects,
+            method: method,
+            dataType: 'mixed',
+            count: extractedObjects.length
+        };
+    }
+    const objects = [];
+    const arrays = [];
+    let pos = 0;
+    while (pos < trimmed.length) {
+        const objStart = trimmed.indexOf('{', pos);
+        const arrStart = trimmed.indexOf('[', pos);
+        if (objStart === -1 && arrStart === -1)
+            break;
+        let nextStart = -1;
+        let nextEnd = -1;
+        let type = null;
+        if (objStart !== -1 && (arrStart === -1 || objStart < arrStart)) {
+            nextStart = objStart;
+            const objEnd = findMatchingBrace(trimmed, objStart);
+            if (objEnd !== -1 && objEnd > objStart) {
+                nextEnd = objEnd;
+                type = 'object';
+            }
+        }
+        else if (arrStart !== -1) {
+            nextStart = arrStart;
+            const arrEnd = findMatchingBracket(trimmed, arrStart);
+            if (arrEnd !== -1 && arrEnd > arrStart) {
+                nextEnd = arrEnd;
+                type = 'array';
+            }
+        }
+        if (nextStart !== -1 && nextEnd !== -1) {
+            const jsonStr = trimmed.slice(nextStart, nextEnd + 1);
+            try {
+                const parsed = JSON.parse(jsonStr);
+                extractedObjects.push(parsed);
+                if (type === 'object')
+                    objects.push(jsonStr);
+                else
+                    arrays.push(jsonStr);
+                pos = nextEnd + 1;
+            }
+            catch { }
+        }
+        else {
+            break;
+        }
+    }
+    if (extractedObjects.length === 0) {
+        return { success: false, error: 'NO_JSON_FOUND' };
+    }
+    const finalMethod = method || (objects.length > 0 && arrays.length > 0 ? 'object' : objects.length > 0 ? 'object' : 'array');
+    return {
+        success: true,
+        data: extractedObjects,
+        method: finalMethod,
+        dataType: objects.length > 0 && arrays.length > 0 ? 'mixed' : objects.length > 0 ? 'object' : 'array',
+        count: extractedObjects.length
+    };
+}
+export const jsonExtract = tool({
+    description: "Extract and parse JSON from a file. Handles markdown code blocks (```json) and raw JSON with string-aware extraction. Returns first JSON found with metadata.",
+    args: {
+        file_path: z.string().describe("Path to file containing JSON (absolute or relative to project directory)"),
+        return_all: z.boolean().default(false).describe("If true, returns all JSON objects found as array; if false (default), returns first only")
+    },
+    execute: async (args, context) => {
+        try {
+            const resolvedPath = path.isAbsolute(args.file_path)
+                ? args.file_path
+                : path.join(context.directory, args.file_path);
+            if (!isPathWithinDirectory(resolvedPath, context.directory)) {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'PATH_TRAVERSAL',
+                        message: 'Path must be within project directory',
+                        details: `Attempted path: ${args.file_path}`,
+                        hints: ['Use a relative path within the project directory', 'Ensure the path does not contain ..']
+                    }
+                }, null, 2);
+            }
+            if (!fs.existsSync(resolvedPath)) {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'FILE_NOT_FOUND',
+                        message: `File not found: ${args.file_path}`,
+                        details: `Resolved path: ${resolvedPath}`,
+                        hints: ['Check the file path for typos', 'Use a relative path from the project root']
+                    }
+                }, null, 2);
+            }
+            const stats = fs.statSync(resolvedPath);
+            if (stats.isDirectory()) {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'FILE_NOT_FOUND',
+                        message: 'Path is a directory, not a file',
+                        details: `Path: ${args.file_path}`,
+                        hints: ['Provide a file path, not a directory']
+                    }
+                }, null, 2);
+            }
+            if (stats.size > MAX_FILE_SIZE) {
+                const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'FILE_TOO_LARGE',
+                        message: `File exceeds maximum size of 200MB`,
+                        details: `File size: ${sizeMB}MB`,
+                        hints: ['Use a smaller file', 'Consider splitting the file', 'Increase the MAX_FILE_SIZE constant']
+                    }
+                }, null, 2);
+            }
+            const ext = path.extname(resolvedPath).toLowerCase();
+            if (BINARY_EXTENSIONS.includes(ext)) {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'BINARY_FILE',
+                        message: `Binary file format not supported: ${ext}`,
+                        details: `File extension: ${ext}`,
+                        hints: ['Use a text-based file (JSON, Markdown, TXT)', 'Provide file contents as plain text']
+                    }
+                }, null, 2);
+            }
+            const content = fs.readFileSync(resolvedPath, 'utf-8');
+            const result = args.return_all
+                ? extractAllJsonFromContent(content)
+                : extractJsonFromContent(content);
+            if (result.success) {
+                return JSON.stringify({
+                    success: true,
+                    data: result.data,
+                    metadata: {
+                        method: result.method,
+                        dataType: result.dataType,
+                        fileSize: stats.size,
+                        ...(args.return_all && result.count !== undefined ? { count: result.count } : {})
+                    }
+                }, null, 2);
+            }
+            else {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: result.error,
+                        message: getErrorMessage(result.error),
+                        details: `File: ${args.file_path}`,
+                        hints: getErrorHints(result.error)
+                    }
+                }, null, 2);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            const code = message.includes('encoding') || message.includes('EILSEQ')
+                ? 'ENCODING_ERROR'
+                : 'NO_JSON_FOUND';
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code,
+                    message: code === 'ENCODING_ERROR'
+                        ? 'File encoding error - could not read as UTF-8'
+                        : 'Unexpected error while extracting JSON',
+                    details: message,
+                    hints: code === 'ENCODING_ERROR'
+                        ? ['Ensure file is UTF-8 encoded', 'Try converting file encoding']
+                        : ['Check file contents', 'Ensure file is not corrupted']
+                }
+            }, null, 2);
+        }
+    }
+});
+function getErrorMessage(code) {
+    const messages = {
+        'EMPTY_FILE': 'File is empty',
+        'NO_JSON_FOUND': 'No valid JSON found in file',
+        'FILE_NOT_FOUND': 'File not found',
+        'FILE_TOO_LARGE': 'File exceeds maximum size',
+        'BINARY_FILE': 'Binary file format not supported',
+        'PATH_TRAVERSAL': 'Path must be within project directory',
+        'ENCODING_ERROR': 'File encoding error - could not read as UTF-8'
+    };
+    return messages[code] || 'Extraction failed';
+}
+function getErrorHints(code) {
+    const hints = {
+        'EMPTY_FILE': ['Provide a file with content'],
+        'NO_JSON_FOUND': [
+            'Ensure file contains valid JSON',
+            'JSON can be in markdown code blocks (```json) or raw',
+            'Both objects {...} and arrays [...] are supported'
+        ],
+        'FILE_NOT_FOUND': ['Check the file path for typos', 'Use a relative path from the project root'],
+        'FILE_TOO_LARGE': ['Use a smaller file', 'Consider splitting the file'],
+        'BINARY_FILE': ['Use a text-based file (JSON, Markdown, TXT)'],
+        'PATH_TRAVERSAL': ['Use a relative path within the project directory', 'Ensure the path does not contain ..'],
+        'ENCODING_ERROR': ['Ensure file is UTF-8 encoded', 'Try converting file encoding']
+    };
+    return hints[code] || ['Check file contents'];
+}

package/dist/misc-tools/json-infer.d.ts

@@ -0,0 +1,13 @@
+import { ToolContext } from '@opencode-ai/plugin/tool';
+import { z } from 'zod';
+export declare const jsonInfer: {
+    description: string;
+    args: {
+        data: z.ZodString;
+        strict: z.ZodDefault<z.ZodBoolean>;
+    };
+    execute(args: {
+        data: string;
+        strict: boolean;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/misc-tools/json-infer.js

@@ -0,0 +1,199 @@
+import { tool } from '@opencode-ai/plugin/tool';
+import { z, toJSONSchema } from 'zod';
+function isISODateString(value) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/.test(value);
+}
+function collectArrayElementTypes(data, strict) {
+    const warnings = [];
+    if (data.length === 0) {
+        warnings.push({
+            code: 'EMPTY_ARRAY',
+            message: 'Empty array - cannot infer element type',
+            details: 'Using "any" as element type since no data available',
+            hints: ['Provide at least one element in the array for type inference', 'Use z.any() if empty arrays are expected']
+        });
+        return { schemas: [z.any()], types: new Set(['any']), warnings };
+    }
+    const typeMap = new Map();
+    for (let i = 0; i < data.length; i++) {
+        const elementSchema = inferZodSchema(data[i], strict);
+        const typeKey = JSON.stringify(elementSchema._zod.def);
+        if (!typeMap.has(typeKey)) {
+            typeMap.set(typeKey, elementSchema);
+        }
+    }
+    const schemas = Array.from(typeMap.values());
+    const types = new Set(schemas.map(s => s._zod.def.type));
+    // Limit union to 2 types per plan specification
+    if (types.size > 2) {
+        const unionTypes = Array.from(types).join(', ');
+        warnings.push({
+            code: 'MIXED_TYPE_ARRAY',
+            message: 'Too many types in array for union',
+            details: `Found ${types.size} types (${unionTypes}), using "any" as element type`,
+            hints: ['Limit array elements to 1 or 2 types for better type inference', 'Consider using explicit schemas for complex mixed-type arrays']
+        });
+        return { schemas: [z.array(z.any())], types: new Set(['any']), warnings };
+    }
+    if (types.size === 2) {
+        const unionTypes = Array.from(types).join(', ');
+        warnings.push({
+            code: 'MIXED_TYPE_ARRAY',
+            message: `Array contains 2 different types: ${unionTypes}`,
+            details: `Types found: ${unionTypes}. Using union type.`,
+            hints: ['For stronger type safety, consider keeping array elements homogeneous', 'Union types are limited to 2 variants for inference']
+        });
+        const unionSchema = z.union(schemas);
+        return { schemas: [z.array(unionSchema)], types, warnings };
+    }
+    return { schemas: [z.array(schemas[0])], types, warnings };
+}
+function inferZodSchema(data, strict) {
+    if (data === null) {
+        return z.null();
+    }
+    if (Array.isArray(data)) {
+        const { schemas, warnings } = collectArrayElementTypes(data, strict);
+        return schemas[0];
+    }
+    if (typeof data === 'object' && data !== null) {
+        const shape = {};
+        for (const [key, value] of Object.entries(data)) {
+            const fieldSchema = inferZodSchema(value, strict);
+            shape[key] = strict ? fieldSchema : fieldSchema.optional();
+        }
+        return z.object(shape);
+    }
+    if (typeof data === 'string') {
+        if (isISODateString(data)) {
+            return z.string().datetime();
+        }
+        return z.string();
+    }
+    if (typeof data === 'number') {
+        return Number.isInteger(data) ? z.number().int() : z.number();
+    }
+    if (typeof data === 'boolean') {
+        return z.boolean();
+    }
+    return z.any();
+}
+function inferZodSchemaWithWarnings(data, strict) {
+    const warnings = [];
+    if (Array.isArray(data)) {
+        const result = collectArrayElementTypes(data, strict);
+        return {
+            schema: result.schemas[0],
+            warnings: result.warnings
+        };
+    }
+    if (typeof data === 'object' && data !== null) {
+        const capturedKeys = new Set();
+        for (const key of Object.keys(data)) {
+            capturedKeys.add(key);
+        }
+        if (capturedKeys.size > 10 && !strict) {
+            warnings.push({
+                code: 'PARTIAL_OBJECT_SCHEMA',
+                message: `Object has many properties (${capturedKeys.size})`,
+                details: `Only fields from first object instance were analyzed for type inference`,
+                hints: ['For complex objects with varying keys, consider using explicit schemas or splitting into smaller, more homogeneous objects']
+            });
+        }
+        const schema = z.object(Object.fromEntries(Object.entries(data).map(([key, value]) => [key, strict ? inferZodSchema(value, true) : inferZodSchema(value, false).optional()])));
+        return { schema, warnings };
+    }
+    if (typeof data === 'string') {
+        if (isISODateString(data)) {
+            return {
+                schema: z.string().datetime(),
+                warnings: []
+            };
+        }
+        return {
+            schema: z.string(),
+            warnings: []
+        };
+    }
+    if (typeof data === 'number') {
+        return {
+            schema: Number.isInteger(data) ? z.number().int() : z.number(),
+            warnings: []
+        };
+    }
+    if (typeof data === 'boolean') {
+        return {
+            schema: z.boolean(),
+            warnings: []
+        };
+    }
+    warnings.push({
+        code: 'UNKNOWN_TYPE',
+        message: 'Unknown value type',
+        details: `Value type: ${typeof data}`,
+        hints: ['Using "any" type for unknown values - consider explicitly defining expected types']
+    });
+    return {
+        schema: z.any(),
+        warnings
+    };
+}
+export const jsonInfer = tool({
+    description: "Infer a JSON Schema from example JSON data. Reports warnings for mixed-type arrays and partial object inference. Generates valid JSON Schema Draft-2020-12.",
+    args: {
+        data: z.string().describe("Example JSON data string"),
+        strict: z.boolean().default(false).describe("If true, all fields are required; if false (default), fields are optional")
+    },
+    execute: async (args, context) => {
+        let parsedData;
+        try {
+            parsedData = JSON.parse(args.data);
+        }
+        catch (e) {
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'INVALID_JSON_DATA',
+                    message: 'Data is not valid JSON',
+                    details: e instanceof Error ? e.message : 'Parse error',
+                    hints: [
+                        'Ensure data is valid JSON syntax',
+                        'Example: {"name": "value"} or [1, 2, 3]'
+                    ]
+                }
+            }, null, 2);
+        }
+        try {
+            const { schema, warnings } = inferZodSchemaWithWarnings(parsedData, args.strict);
+            const jsonSchema = toJSONSchema(schema);
+            const response = {
+                success: true,
+                data: jsonSchema,
+                metadata: {
+                    inferredType: Array.isArray(parsedData) ? 'array' :
+                        typeof parsedData === 'object' ? 'object' : typeof parsedData,
+                    strictMode: args.strict
+                }
+            };
+            if (warnings.length > 0) {
+                response.warnings = warnings;
+            }
+            return JSON.stringify(response, null, 2);
+        }
+        catch (e) {
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'INFERENCE_FAILED',
+                    message: 'Failed to infer schema from data',
+                    details: e instanceof Error ? e.message : 'Inference error',
+                    hints: [
+                        'Try with simpler data',
+                        'Ensure data structure is not circular',
+                        'Check for complex nested structures'
+                    ]
+                }
+            }, null, 2);
+        }
+    }
+});