@yeyuan98/opencode-bioresearcher-plugin 1.3.1-alpha.1 → 1.4.0

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

@@ -0,0 +1,33 @@
+import { ToolContext } from '@opencode-ai/plugin/tool';
+export declare const jsonValidate: {
+    description: string;
+    args: {
+        data: any;
+        schema: any;
+        version: any;
+    };
+    execute(args: {
+        [x: string]: any;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const jsonExtract: {
+    description: string;
+    args: {
+        content: any;
+        path: any;
+    };
+    execute(args: {
+        [x: string]: any;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const jsonInferSchema: {
+    description: string;
+    args: {
+        data: any;
+        title: any;
+        strict: any;
+    };
+    execute(args: {
+        [x: string]: any;
+    }, context: ToolContext): Promise<string>;
+};

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

@@ -0,0 +1,187 @@
+import { tool } from '@opencode-ai/plugin/tool';
+const zod = require('zod');
+function getFromJSONSchema() {
+    if (zod.fromJSONSchema) {
+        return zod.fromJSONSchema;
+    }
+    const v4classic = require('zod/v4/classic/external.js');
+    if (v4classic.fromJSONSchema) {
+        return v4classic.fromJSONSchema;
+    }
+    throw new Error('fromJSONSchema not available in zod package');
+}
+const fromJSONSchema = getFromJSONSchema();
+export const jsonValidate = tool({
+    description: `Validate JSON data against a JSON Schema.
+Returns validation result with detailed error paths and messages.
+Supports JSON Schema draft-04, draft-07, draft-2020-12, and OpenAPI 3.0.`,
+    args: {
+        data: z.any().describe("JSON data to validate (object, array, or primitive)"),
+        schema: z.any().describe("JSON Schema object to validate against"),
+        version: z.enum(["draft-04", "draft-07", "draft-2020-12", "openapi-3.0"])
+            .optional()
+            .default("draft-2020-12")
+            .describe("JSON Schema version (default: draft-2020-12)")
+    },
+    execute: async (args) => {
+        try {
+            const zodSchema = z.fromJSONSchema(args.schema, {
+                defaultTarget: args.version
+            });
+            const result = zodSchema.safeParse(args.data);
+            if (result.success) {
+                return JSON.stringify({
+                    valid: true,
+                    data: result.data
+                }, null, 2);
+            }
+            else {
+                const errors = result.error.issues.map((issue) => ({
+                    path: issue.path.join('.') || '(root)',
+                    message: issue.message,
+                    code: issue.code
+                }));
+                return JSON.stringify({
+                    valid: false,
+                    errors,
+                    errorCount: errors.length
+                }, null, 2);
+            }
+        }
+        catch (e) {
+            return JSON.stringify({
+                valid: false,
+                schemaError: e instanceof Error ? e.message : 'Unknown schema error'
+            }, null, 2);
+        }
+    }
+});
+export const jsonExtract = tool({
+    description: `Extract JSON from markdown or text content.
+Handles code blocks (\`\`\`json) and raw {...} or [...] patterns.
+Returns extracted JSON or error with details.`,
+    args: {
+        content: z.string().describe("Markdown or text content containing JSON"),
+        path: z.string().optional()
+            .describe("JSONPath to extract nested value (e.g., 'data.items.0')")
+    },
+    execute: async (args) => {
+        let jsonStr = null;
+        const codeBlockMatch = args.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+        if (codeBlockMatch) {
+            jsonStr = codeBlockMatch[1].trim();
+        }
+        if (!jsonStr) {
+            const objStart = args.content.indexOf('{');
+            const arrStart = args.content.indexOf('[');
+            if (objStart !== -1 || arrStart !== -1) {
+                const startChar = objStart !== -1 && (arrStart === -1 || objStart < arrStart) ? '{' : '[';
+                const endChar = startChar === '{' ? '}' : ']';
+                const startIndex = args.content.indexOf(startChar);
+                let depth = 0;
+                let endIndex = -1;
+                for (let i = startIndex; i < args.content.length; i++) {
+                    if (args.content[i] === startChar)
+                        depth++;
+                    if (args.content[i] === endChar)
+                        depth--;
+                    if (depth === 0) {
+                        endIndex = i + 1;
+                        break;
+                    }
+                }
+                if (endIndex !== -1) {
+                    jsonStr = args.content.slice(startIndex, endIndex);
+                }
+            }
+        }
+        if (!jsonStr) {
+            return JSON.stringify({
+                success: false,
+                error: "No JSON found in content"
+            }, null, 2);
+        }
+        try {
+            let data = JSON.parse(jsonStr);
+            if (args.path) {
+                const parts = args.path.split('.');
+                for (const part of parts) {
+                    if (data === null || data === undefined) {
+                        return JSON.stringify({
+                            success: false,
+                            error: `Path '${args.path}' not found (null/undefined at '${part}')`
+                        }, null, 2);
+                    }
+                    data = data[part];
+                }
+            }
+            return JSON.stringify({
+                success: true,
+                data
+            }, null, 2);
+        }
+        catch (e) {
+            return JSON.stringify({
+                success: false,
+                error: `Invalid JSON: ${e instanceof Error ? e.message : 'Unknown error'}`,
+                extractedText: jsonStr.length > 200 ? jsonStr.slice(0, 200) + '...' : jsonStr
+            }, null, 2);
+        }
+    }
+});
+export const jsonInferSchema = tool({
+    description: `Infer a JSON Schema from example JSON data.
+Useful for creating schemas from sample data.`,
+    args: {
+        data: z.any().describe("Example JSON data to infer schema from"),
+        title: z.string().optional().describe("Optional schema title"),
+        strict: z.boolean().optional().default(false)
+            .describe("If true, set additionalProperties: false for objects")
+    },
+    execute: async (args) => {
+        function inferType(value, strict) {
+            if (value === null)
+                return { type: "null" };
+            if (typeof value === "string")
+                return { type: "string" };
+            if (typeof value === "boolean")
+                return { type: "boolean" };
+            if (typeof value === "number") {
+                return Number.isInteger(value) ? { type: "integer" } : { type: "number" };
+            }
+            if (Array.isArray(value)) {
+                if (value.length === 0) {
+                    return { type: "array", items: {} };
+                }
+                return { type: "array", items: inferType(value[0], strict) };
+            }
+            if (typeof value === "object" && value !== null) {
+                const obj = value;
+                const properties = {};
+                const required = [];
+                for (const [key, val] of Object.entries(obj)) {
+                    properties[key] = inferType(val, strict);
+                    required.push(key);
+                }
+                const schema = {
+                    type: "object",
+                    properties,
+                    required
+                };
+                if (strict) {
+                    schema.additionalProperties = false;
+                }
+                return schema;
+            }
+            return {};
+        }
+        const schema = {
+            $schema: "https://json-schema.org/draft/2020-12/schema",
+            ...inferType(args.data, args.strict ?? false)
+        };
+        if (args.title) {
+            schema.title = args.title;
+        }
+        return JSON.stringify(schema, null, 2);
+    }
+});

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

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

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

@@ -0,0 +1,228 @@
+import { tool } from '@opencode-ai/plugin/tool';
+import { z, fromJSONSchema } from 'zod';
+import * as path from 'path';
+const UNSUPPORTED_SCHEMA_FEATURES = [
+    'not', 'unevaluatedItems', 'unevaluatedProperties',
+    'if', 'then', 'else', 'dependentSchemas', 'dependentRequired'
+];
+const SILENTLY_IGNORED_FEATURES = [
+    'uniqueItems', 'contains', 'minContains', 'maxContains'
+];
+function analyzeSchemaFeatures(schema, prefix = '') {
+    const result = { unsupported: [], ignored: [] };
+    if (typeof schema !== 'object' || schema === null)
+        return result;
+    const obj = schema;
+    for (const feature of UNSUPPORTED_SCHEMA_FEATURES) {
+        if (feature in obj) {
+            result.unsupported.push(prefix ? `${prefix}.${feature}` : feature);
+        }
+    }
+    for (const feature of SILENTLY_IGNORED_FEATURES) {
+        if (feature in obj) {
+            result.ignored.push(prefix ? `${prefix}.${feature}` : feature);
+        }
+    }
+    if (obj.properties && typeof obj.properties === 'object') {
+        for (const [key, value] of Object.entries(obj.properties)) {
+            const nested = analyzeSchemaFeatures(value, prefix ? `${prefix}.properties.${key}` : `properties.${key}`);
+            result.unsupported.push(...nested.unsupported);
+            result.ignored.push(...nested.ignored);
+        }
+    }
+    if (obj.items) {
+        const nested = analyzeSchemaFeatures(obj.items, prefix ? `${prefix}.items` : 'items');
+        result.unsupported.push(...nested.unsupported);
+        result.ignored.push(...nested.ignored);
+    }
+    return result;
+}
+function formatZodError(error) {
+    return error.issues.map(issue => {
+        const result = {
+            path: issue.path.join('.') || '(root)',
+            message: issue.message,
+            code: issue.code
+        };
+        if (issue.code === 'invalid_type') {
+            const typedIssue = issue;
+            result.expected = typeof typedIssue.expected === 'string'
+                ? 'string'
+                : typedIssue.expected === 'number'
+                    ? 'number'
+                    : String(typedIssue.expected);
+            result.received = typeof typedIssue.input === 'string'
+                ? 'string'
+                : String(typedIssue.input);
+        }
+        if (issue.code === 'too_small') {
+            const typedIssue = issue;
+            result.constraint = {
+                type: typedIssue.origin === 'string' ? 'minLength' : 'minimum',
+                value: String(typedIssue.minimum)
+            };
+        }
+        if (issue.code === 'too_big') {
+            const typedIssue = issue;
+            result.constraint = {
+                type: typedIssue.origin === 'string' ? 'maxLength' : 'maximum',
+                value: String(typedIssue.maximum)
+            };
+        }
+        if (issue.code === 'invalid_format') {
+            const formatIssue = issue;
+            result.constraint = {
+                type: 'format',
+                value: String(formatIssue.format)
+            };
+        }
+        return result;
+    });
+}
+export const jsonValidate = tool({
+    description: "Validate JSON data against a JSON Schema (supports Draft-4, Draft-7, Draft-2020-12, OpenAPI 3.0). Returns detailed validation results with warnings for unsupported/ignored schema features.",
+    args: {
+        data: z.string().describe("JSON data string to validate"),
+        schema: z.string().describe("JSON Schema string or file path (auto-reads from file if path detected)")
+    },
+    execute: async (args, context) => {
+        let parsedData;
+        let parsedSchema;
+        let schemaString = args.schema;
+        const isWindowsPath = /^[A-Za-z]:[/\\]/.test(args.schema);
+        const isUnixPath = /^\//.test(args.schema);
+        const isRelativePath = /^\.{1,2}(\/|\\)/.test(args.schema);
+        if (isWindowsPath || isUnixPath || isRelativePath) {
+            const resolvedPath = path.isAbsolute(args.schema)
+                ? args.schema
+                : path.join(context.directory, args.schema);
+            try {
+                const fs = await import('fs');
+                schemaString = fs.readFileSync(resolvedPath, 'utf-8');
+            }
+            catch (e) {
+                return JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'INVALID_JSON_SCHEMA',
+                        message: 'Failed to read schema from file',
+                        details: e instanceof Error ? e.message : 'Unknown error',
+                        hints: [
+                            'Check the file path for typos',
+                            'Ensure file exists and is accessible',
+                            'Use a relative path from the project directory'
+                        ]
+                    }
+                }, null, 2);
+            }
+        }
+        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',
+                        'Check for missing quotes, trailing commas, or unescaped characters'
+                    ]
+                }
+            }, null, 2);
+        }
+        try {
+            parsedSchema = JSON.parse(schemaString);
+        }
+        catch (e) {
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'INVALID_JSON_SCHEMA',
+                    message: 'Schema is not valid JSON',
+                    details: e instanceof Error ? e.message : 'Parse error',
+                    hints: [
+                        'Ensure schema is valid JSON syntax',
+                        'Check JSON Schema syntax at https://json-schema.org'
+                    ]
+                }
+            }, null, 2);
+        }
+        const analysis = analyzeSchemaFeatures(parsedSchema);
+        if (analysis.unsupported.length > 0) {
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'UNSUPPORTED_SCHEMA_FEATURE',
+                    message: 'Schema uses features not supported by Zod',
+                    details: {
+                        unsupportedFeatures: analysis.unsupported,
+                        explanation: 'These JSON Schema features cannot be converted to Zod schemas'
+                    },
+                    hints: [
+                        'Remove unsupported features from schema',
+                        `Unsupported features: ${analysis.unsupported.join(', ')}`,
+                        'Consider using a simpler schema structure'
+                    ]
+                }
+            }, null, 2);
+        }
+        let zodSchema;
+        try {
+            zodSchema = fromJSONSchema(parsedSchema);
+        }
+        catch (e) {
+            return JSON.stringify({
+                success: false,
+                error: {
+                    code: 'UNSUPPORTED_SCHEMA_FEATURE',
+                    message: 'Failed to convert JSON Schema to validation schema',
+                    details: e instanceof Error ? e.message : 'Conversion error',
+                    hints: [
+                        'Schema may use unsupported features',
+                        'Check schema syntax and structure'
+                    ]
+                }
+            }, null, 2);
+        }
+        const result = zodSchema.safeParse(parsedData);
+        if (result.success) {
+            const response = {
+                success: true,
+                data: result.data,
+                metadata: {
+                    errorCount: 0,
+                    schemaFeatures: {
+                        validated: Object.keys(parsedSchema).filter(k => !SILENTLY_IGNORED_FEATURES.includes(k)),
+                        ignored: analysis.ignored
+                    }
+                }
+            };
+            if (analysis.ignored.length > 0) {
+                response.warnings = analysis.ignored.map((feature) => ({
+                    code: 'IGNORED_SCHEMA_FEATURE',
+                    message: `Schema feature '${feature}' is not validated`,
+                    details: 'This feature is silently ignored by Zod - data may not match intended constraints'
+                }));
+            }
+            return JSON.stringify(response, null, 2);
+        }
+        else {
+            return JSON.stringify({
+                success: true,
+                data: null,
+                valid: false,
+                errors: formatZodError(result.error),
+                metadata: {
+                    errorCount: result.error.issues.length,
+                    schemaFeatures: {
+                        validated: Object.keys(parsedSchema).filter(k => !SILENTLY_IGNORED_FEATURES.includes(k)),
+                        ignored: analysis.ignored
+                    }
+                }
+            }, null, 2);
+        }
+    }
+});

package/dist/skills/bioresearcher-core/README.md

@@ -0,0 +1,210 @@
+# BioResearcher Core
+
+Core library skill providing reusable patterns and utilities for BioResearcher skills.
+
+## Overview
+
+BioResearcher Core provides:
+- **Workflow patterns** for common operations (retry, progress, subagent waves)
+- **Data handling patterns** for JSON and table operations
+- **Python utilities** for template generation
+- **Tool-first architecture** using existing plugin tools
+
+## Installation
+
+No installation required. This skill uses only:
+- Existing plugin tools (jsonExtract, jsonValidate, etc.)
+- Python standard library
+
+## Quick Start
+
+### Load the Skill
+
+```
+skill bioresearcher-core
+```
+
+### Extract Skill Path
+
+From the `<skill_files>` section in the skill tool output, extract the `<skill_path>` value for use in commands.
+
+### Use a Pattern
+
+```
+Read <skill_path>/patterns/retry.md
+```
+
+### Run Python Script
+
+```bash
+uv run python <skill_path>/python/template.py generate-batches \
+  --template template.md \
+  --contexts contexts.json \
+  --output-dir ./outputs
+```
+
+## Available Patterns
+
+### Workflow Control
+
+| Pattern | Description | File |
+|---------|-------------|------|
+| Retry | Retry with backoff using blockingTimer | `patterns/retry.md` |
+| Progress | Track and report batch progress | `patterns/progress.md` |
+| Subagent Waves | Parallel subagent processing | `patterns/subagent-waves.md` |
+| Shell Commands | Cross-platform command generation | `patterns/shell-commands.md` |
+| User Confirmation | Request user confirmation | `patterns/user-confirmation.md` |
+
+### Data Handling
+
+| Pattern | Description | File |
+|---------|-------------|------|
+| JSON Tools | jsonExtract/jsonValidate/jsonInfer | `patterns/json-tools.md` |
+| Table Tools | Combine outputs with table tools | `patterns/table-tools.md` |
+| Data Exchange | Main/subagent communication | `patterns/data-exchange.md` |
+| Calculator | In-workflow calculations | `patterns/calculator.md` |
+
+## Available Tools
+
+These tools are always available without loading pattern files:
+
+### JSON Tools
+
+| Tool | Description |
+|------|-------------|
+| `jsonExtract` | Extract JSON from files |
+| `jsonValidate` | Validate JSON against schemas |
+| `jsonInfer` | Infer schemas from data |
+
+### Utility Tools
+
+| Tool | Description |
+|------|-------------|
+| `blockingTimer` | Blocking delays (0-300 seconds) |
+| `calculator` | Mathematical expressions |
+
+### Table Tools
+
+| Tool | Description |
+|------|-------------|
+| `tableCreateFile` | Create Excel/CSV from data |
+| `tableAppendRows` | Append rows to tables |
+
+## Python Utilities
+
+### Template Engine
+
+Location: `python/template.py`
+
+Commands:
+- `fill` - Generate single file from template
+- `generate-batches` - Generate multiple files from template
+- `escape` - Escape text for markdown
+
+See `python/template.md` for full documentation.
+
+## Examples
+
+### Example Files
+
+| File | Description |
+|------|-------------|
+| `examples/template.md` | Example template with placeholders |
+| `examples/contexts.json` | Example contexts for batch generation |
+| `examples/data-exchange-example.md` | Complete data exchange workflow |
+
+## Architecture
+
+### Tool-First Design
+
+This skill maximizes use of existing plugin tools:
+
+```
+┌─────────────────────────────────────────────────┐
+│              BioResearcher Core                  │
+├─────────────────────────────────────────────────┤
+│  Patterns (markdown)    │  Python Utilities     │
+│  - retry.md             │  - template.py        │
+│  - progress.md          │                       │
+│  - subagent-waves.md    │                       │
+│  - json-tools.md        │                       │
+│  - table-tools.md       │                       │
+│  - data-exchange.md     │                       │
+│  - calculator.md        │                       │
+│  - shell-commands.md    │                       │
+│  - user-confirmation.md │                       │
+├─────────────────────────┴───────────────────────┤
+│              Plugin Tools                        │
+│  jsonExtract │ jsonValidate │ jsonInfer         │
+│  blockingTimer │ calculator                      │
+│  tableCreateFile │ tableAppendRows              │
+└─────────────────────────────────────────────────┘
+```
+
+### Pattern Modules
+
+Each pattern is a self-contained markdown file:
+- Independent (no dependencies on other patterns)
+- Self-documenting (explains itself)
+- Minimal loading (agent reads only what it needs)
+
+## Integration with Other Skills
+
+### long-table-summary
+
+BioResearcher Core can be used by long-table-summary:
+- Use `jsonExtract` instead of manual JSON parsing
+- Use `jsonValidate` for schema validation
+- Apply retry/progress patterns
+- Use template.py for prompt generation
+
+### pubmed-weekly
+
+BioResearcher Core can be used by pubmed-weekly:
+- Apply retry pattern for download failures
+- Use shell-commands pattern for cross-platform support
+
+## Design Principles
+
+1. **Tool-first**: Use existing tools before creating Python scripts
+2. **Self-contained**: Each pattern is independent
+3. **Minimal dependencies**: Only Python standard library
+4. **Clear documentation**: Every file documents itself
+5. **Standard protocols**: JSON for data exchange
+
+## Directory Structure
+
+```
+plugin/skills/bioresearcher-core/
+├── SKILL.md                    # Routing document
+├── README.md                   # This file
+├── patterns/                   # Workflow patterns
+│   ├── retry.md
+│   ├── progress.md
+│   ├── subagent-waves.md
+│   ├── shell-commands.md
+│   ├── user-confirmation.md
+│   ├── json-tools.md
+│   ├── table-tools.md
+│   ├── data-exchange.md
+│   └── calculator.md
+├── python/                     # Python utilities
+│   ├── template.py
+│   └── template.md
+└── examples/                   # Example files
+    ├── template.md
+    ├── contexts.json
+    └── data-exchange-example.md
+```
+
+## Contributing
+
+When adding new patterns:
+1. Create self-contained markdown file in `patterns/`
+2. Follow existing pattern structure
+3. Include examples and error handling
+4. Update SKILL.md with new pattern reference
+
+## License
+
+Part of the BioResearcher plugin ecosystem.