diff --git a/GUIDELINES.md b/GUIDELINES.md
index aecd3ef..0b93475 100644
--- a/GUIDELINES.md
+++ b/GUIDELINES.md
@@ -1,23 +1,28 @@
---
-title: BB Tools Framework Guidelines
+title: BB Plugin Framework Guidelines
project: bb-tools
-version: 1.0.0
+version: 1.1.0
created: 2025-11-02
-updated: 2025-11-02
+updated: 2025-11-04
purpose: Guidelines for LLM collaboration on bb-tools framework development
+note: Project may be renamed to bb-plugins in future
---
-# BB Tools Framework Guidelines
+# BB Plugin Framework Guidelines
## Project Purpose and Scope
### Overview
-bb-tools (@beyondbetter/tools) is the core framework/library for building tools that work with the Beyond Better (BB) AI assistant. This project provides base classes, interfaces, types, and utilities needed to create properly structured BB tools.
+bb-tools (@beyondbetter/tools) is the core framework/library for building plugins that work with the Beyond Better (BB) AI assistant. This project provides base classes, interfaces, types, and utilities needed to create properly structured BB plugins containing tools and datasources.
**IMPORTANT**: These guidelines are for working on the bb-tools framework itself, NOT for users/consumers of the framework. The audience is the LLM assisting with framework development, maintenance, and enhancement.
+**NOTE**: This project may be renamed to `bb-plugins` in the future to better reflect its purpose.
+
### Project Goals
- Provide robust base classes (LLMTool) for tool creation
+- Define standardized plugin structure (.bbplugin format with manifest.json)
+- Support both tool and datasource components within plugins
- Define standardized interfaces (IProjectEditor, IConversationInteraction)
- Supply formatting utilities for browser (JSX/Preact) and console (ANSI)
- Maintain comprehensive type definitions
@@ -34,16 +39,18 @@ bb-tools (@beyondbetter/tools) is the core framework/library for building tools
### Project Scope
**In Scope:**
- Framework core classes and utilities
+- Plugin structure definition (.bbplugin format)
+- Plugin manifest schema and validation
- Type definitions and interfaces
-- Example tools demonstrating framework usage
-- Documentation for tool creators
+- Example plugins demonstrating framework usage
+- Documentation for plugin creators
- JSR publishing configuration
**Out of Scope:**
-- Individual tools created by framework consumers
+- Individual plugins created by framework consumers
- Beyond Better (BB) main application code
-- Tool runtime environment (handled by BB)
-- Tool distribution/marketplace
+- Plugin runtime environment (handled by BB)
+- Plugin distribution marketplace (future BB feature)
## Available Data Sources and Resources
@@ -77,24 +84,33 @@ deno.lock # Dependency lock file
#### Documentation (`docs/`)
```
-CREATING_TOOLS.md # Guide for tool creators (consumers)
-TESTING.md # Testing guidelines for tools
+CREATING_TOOLS.md # Guide for plugin creators (consumers)
+TESTING.md # Testing guidelines for plugins
tools.md # Comprehensive framework reference
+plugin-manifest-schema.json # JSON schema for manifest.json
```
-#### Example Tools (`examples/`)
+#### Example Plugins (`examples/`)
```
mod.ts # Examples module exports
+search-plugin.bbplugin/
+ ├── manifest.json # Plugin metadata
+ └── search-project.tool/
+ ├── tool.ts # Tool implementation
+ ├── formatter.browser.tsx # Browser formatting
+ ├── formatter.console.ts # Console formatting
+ ├── info.json # Tool metadata
+ ├── types.ts # Tool-specific types
+ ├── tool.test.ts # Tool tests
+ └── README.md # Tool documentation
+browser-plugin.bbplugin/
+ ├── manifest.json
+ └── open-in-browser.tool/
+ └── (same structure)
+
+# Legacy (deprecated, for backward compatibility):
search_project.tool/
- ├── tool.ts # Tool implementation
- ├── formatter.browser.tsx # Browser formatting
- ├── formatter.console.ts # Console formatting
- ├── info.json # Tool metadata
- ├── types.ts # Tool-specific types
- ├── tool.test.ts # Tool tests
- └── README.md # Tool documentation
open_in_browser.tool/
- └── (same structure)
```
#### Other Files
@@ -113,11 +129,13 @@ LICENSE # MIT License
- Update type definitions if interfaces change
- Test with example tools after changes
-2. **Example Tool Development**
- - Follow established tool structure
- - Include all standard files (tool.ts, formatters, tests, README, info.json)
+2. **Example Plugin Development**
+ - Create .bbplugin directory with manifest.json
+ - Follow established plugin and tool structure
+ - Include all standard files (manifest.json, tool.ts, formatters, tests, README, info.json)
- Use framework utilities consistently
- Demonstrate specific framework features
+ - Show both single-tool and multi-tool plugin patterns
3. **Documentation Updates**
- Keep in sync with code changes
@@ -182,25 +200,57 @@ LICENSE # MIT License
- GitHub Actions workflow handles publishing
- Follow semantic versioning
-## Tool Creation Guidelines
+## Plugin Creation Guidelines
+
+### Standard Plugin Structure
+When creating example plugins or documenting plugin patterns:
-### Standard Tool Structure
-When creating example tools or documenting tool patterns:
+```
+plugin-name.bbplugin/
+├── manifest.json # Required: Plugin metadata
+├── tool-name.tool/
+│ ├── tool.ts # Tool implementation (extends LLMTool)
+│ ├── formatter.browser.tsx # Browser UI formatting (JSX/Preact)
+│ ├── formatter.console.ts # Console output formatting (ANSI)
+│ ├── info.json # Tool metadata and examples
+│ ├── types.ts # Tool-specific types (if needed)
+│ ├── tool.test.ts # Comprehensive tests
+│ └── README.md # Tool documentation
+└── another-tool.tool/ # Additional tools (optional)
+ └── (same structure)
+```
+### Legacy Tool Structure (Deprecated)
```
-tool_name.tool/
-├── tool.ts # Tool implementation (extends LLMTool)
-├── formatter.browser.tsx # Browser UI formatting (JSX/Preact)
-├── formatter.console.ts # Console output formatting (ANSI)
-├── info.json # Tool metadata and examples
-├── types.ts # Tool-specific types (if needed)
-├── tool.test.ts # Comprehensive tests
-└── README.md # Tool documentation
+tool_name.tool/ # Standalone tool (deprecated)
+├── tool.ts
+├── formatter.browser.tsx
+├── formatter.console.ts
+├── info.json
+├── types.ts
+├── tool.test.ts
+└── README.md
```
+**Note**: While BB still supports standalone `.tool` directories for backward compatibility, all new development should use the `.bbplugin` structure.
+
+### Plugin Manifest Requirements
+
+**manifest.json** at plugin root:
+- **name**: Plugin package name (kebab-case)
+- **version**: Semantic version (major.minor.patch)
+- **author**: Creator name or organization
+- **description**: Brief plugin description
+- **license**: License identifier (e.g., MIT, Apache-2.0)
+- **tools**: Array of tool directory names (e.g., ["search-tool.tool"])
+- **datasources**: Array of datasource directory names (optional, future support)
+- **bbVersion**: Minimum BB version (e.g., ">=0.9.0")
+
+See [Plugin Manifest Schema](#plugin-manifest-schema) for complete specification.
+
### Key Implementation Requirements
-1. **Tool Class**
+1. **Tool Class** (within each .tool directory)
- Extend `LLMTool` base class
- Implement `inputSchema` getter (JSON Schema)
- Implement `runTool` method
@@ -447,15 +497,17 @@ When reviewing or modifying framework code:
6. **Consider examples**: Should example tools demonstrate this?
7. **Test with examples**: Verify examples still work
-### Creating a New Example Tool
+### Creating a New Example Plugin
-1. **Create directory**: `examples/tool_name.tool/`
-2. **Implement tool.ts**: Extend LLMTool, implement required methods
-3. **Create formatters**: Both browser.tsx and console.ts
-4. **Add info.json**: Metadata and examples
-5. **Write tests**: Comprehensive coverage
-6. **Document in README**: Usage and implementation details
-7. **Export from examples/mod.ts**: Make available to framework users
+1. **Create plugin directory**: `examples/plugin-name.bbplugin/`
+2. **Create manifest.json**: Plugin metadata with name, version, author, description, tools list
+3. **Create tool directory**: `examples/plugin-name.bbplugin/tool-name.tool/`
+4. **Implement tool.ts**: Extend LLMTool, implement required methods
+5. **Create formatters**: Both browser.tsx and console.ts
+6. **Add info.json**: Tool metadata and examples
+7. **Write tests**: Comprehensive coverage for each tool
+8. **Document in README**: Plugin overview and tool usage
+9. **Export from examples/mod.ts**: Make available to framework users
### Updating Documentation
@@ -477,22 +529,53 @@ When reviewing or modifying framework code:
## Framework-Specific Considerations
+### Plugin Manifest Schema
+
+The manifest.json schema is defined in `docs/plugin-manifest-schema.json`. Key requirements:
+
+**Required Fields:**
+- `name`: Kebab-case plugin identifier
+- `version`: Semantic version string
+- `description`: Plugin description (10-500 chars)
+- `tools`: Array of tool directory names
+
+**Optional Fields:**
+- `author`: Creator name/organization
+- `license`: License identifier (SPDX format)
+- `datasources`: Array of datasource directory names
+- `bbVersion`: Minimum BB version (semver range)
+- `homepage`: Plugin homepage URL
+- `repository`: Repository information object
+- `keywords`: Array of discovery keywords
+
+**Validation:**
+- All listed tools must exist as directories
+- Directory names must match exactly (case-sensitive)
+- Version must follow semver format
+- Plugin name must be valid kebab-case
+
### Understanding the Framework Architecture
**Core Concepts:**
+- **Plugin Package**: .bbplugin directory containing manifest and components
+- **Plugin Manifest**: manifest.json with metadata and component lists
- **LLMTool**: Base class providing common functionality
+- **Tool Components**: Individual .tool directories within plugin
+- **Datasource Components**: Individual .datasource directories (future support)
- **IProjectEditor**: Interface for file/project operations (consumed by tools)
- **IConversationInteraction**: Interface for conversation context (consumed by tools)
- **Formatters**: Dual formatting for browser UI and console output
- **Tool Metadata**: info.json provides tool information to BB
-**Tool Lifecycle:**
-1. Tool registered with BB
-2. LLM decides to use tool based on capabilities
-3. BB validates input against `inputSchema`
-4. Tool's `runTool` method executes
-5. Results formatted for display (browser or console)
-6. Results returned to LLM
+**Plugin Lifecycle:**
+1. Plugin discovered in configured directories
+2. Manifest validated by BB
+3. Tools registered with BB from plugin
+4. LLM decides to use tool based on capabilities
+5. BB validates input against `inputSchema`
+6. Tool's `runTool` method executes
+7. Results formatted for display (browser or console)
+8. Results returned to LLM
### Maintaining Backward Compatibility
@@ -806,6 +889,17 @@ Deno.test({
## Version History
+### 1.1.0 (2025-11-04)
+- Updated for new .bbplugin plugin structure
+- Added plugin manifest requirements and schema
+- Documented plugin packaging and distribution
+- Updated all documentation for plugin-first approach
+- Added plugin-manifest-schema.json
+- Marked standalone .tool structure as deprecated
+- Added datasource component support (future)
+- Updated example structure to show plugin packages
+- Note: Project may be renamed to bb-plugins
+
### 1.0.1 (2025-11-02)
- Enhanced with details from docs/CREATING_TOOLS.md
- Added tool types and patterns (File System, Data Processing, Network)
diff --git a/README.md b/README.md
index 8a18a7b..1a877c7 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,27 @@
[](https://jsr.io/@beyondbetter/tools)
[](https://jsr.io/@beyondbetter/tools)
-Core tool infrastructure for building BB (Beyond Better) AI assistant tools. This package provides
-the base classes, interfaces, and types needed to create tools that can be used with the BB AI
-assistant.
+Core plugin infrastructure for building BB (Beyond Better) AI assistant plugins. This package provides
+the base classes, interfaces, types, and plugin structure needed to create plugins containing tools and
+datasources that can be used with the BB AI assistant.
+
+**Note**: This package may be renamed to `@beyondbetter/plugins` in the future.
## Features
-- Base tool class with standardized interfaces
-- Browser and console formatting with consistent styling
-- Comprehensive type definitions
-- Project and conversation management interfaces
-- Built-in input validation using JSON Schema
-- Extensive testing utilities
-- Tool metadata and examples support
+- **Plugin Structure**: Structured `.bbplugin` format with manifest support
+- **Multi-Component Support**: Package multiple tools and datasources together
+- **Base Tool Class**: Standardized LLMTool base class with consistent interfaces
+- **Dual Formatting**: Browser (JSX/Preact) and console (ANSI) output formatting
+- **Type Safety**: Comprehensive TypeScript type definitions
+- **Project & Conversation**: Standardized interfaces for file and conversation management
+- **Input Validation**: Built-in JSON Schema validation
+- **Testing Utilities**: Extensive testing helpers and utilities
+- **Metadata Support**: Plugin and tool metadata with examples
+- **Version Management**: Semantic versioning with BB compatibility checks
+- **Distribution Ready**: Double-click installation support (.bbplugin files)
+
+**Note**: Standalone `.tool` directories are deprecated but still supported for backward compatibility.
## Installation
@@ -30,18 +38,37 @@ import { LLMTool } from "jsr:@beyondbetter/tools";
## Quick Start
-1. Create tool structure:
+### Plugin Structure
+
+1. Create plugin package:
```
-my-tool/
-├── tool.ts # Main implementation
-├── info.json # Tool metadata
-├── formatter.browser.tsx # Browser formatting
-├── formatter.console.ts # Console formatting
-└── tool.test.ts # Tests
+my-plugin.bbplugin/
+├── manifest.json # Plugin metadata (required)
+└── my-tool.tool/ # Tool directory
+ ├── tool.ts # Main implementation
+ ├── info.json # Tool metadata
+ ├── formatter.browser.tsx # Browser formatting
+ ├── formatter.console.ts # Console formatting
+ └── tool.test.ts # Tests
```
-2. Define tool metadata (info.json):
+2. Create plugin manifest (manifest.json):
+
+```json
+{
+ "name": "my-plugin",
+ "version": "1.0.0",
+ "author": "Your Name",
+ "description": "Description of your plugin",
+ "license": "MIT",
+ "tools": ["my-tool.tool"],
+ "datasources": [],
+ "bbVersion": ">=0.9.0"
+}
+```
+
+3. Define tool metadata (my-tool.tool/info.json):
```json
{
@@ -61,7 +88,7 @@ my-tool/
}
```
-3. Implement the tool (tool.ts):
+4. Implement the tool (my-tool.tool/tool.ts):
```typescript
import LLMTool, {
@@ -123,7 +150,7 @@ class MyTool extends LLMTool {
}
```
-4. Implement browser formatting (formatter.browser.tsx):
+5. Implement browser formatting (my-tool.tool/formatter.browser.tsx):
```typescript
/** @jsxImportSource preact */
@@ -154,7 +181,7 @@ export function formatLogEntryToolUse(
}
```
-5. Implement console formatting (formatter.console.ts):
+6. Implement console formatting (my-tool.tool/formatter.console.ts):
```typescript
import { stripIndents } from 'common-tags';
@@ -183,7 +210,19 @@ export function formatLogEntryToolUse(
}
```
-6. Use the tool:
+7. Install and use the plugin:
+
+```bash
+# Copy plugin to BB plugins directory
+cp -r my-plugin.bbplugin ~/.config/bb/plugins/
+
+# Or double-click the .bbplugin directory (macOS/Windows)
+# BB will show installation dialog
+
+# Restart BB API to load the plugin
+```
+
+8. Use the tool:
```typescript
const tool = new MyTool();
@@ -202,9 +241,11 @@ const result = await tool.runTool(
## Documentation
-- [Creating Tools](./docs/CREATING_TOOLS.md) - Detailed guide for creating new tools
+- [Creating Plugins](./docs/CREATING_TOOLS.md) - Detailed guide for creating new plugins
- [Testing Guide](./docs/TESTING.md) - Testing requirements and guidelines
-- [Tools Reference](./docs/tools.md) - Comprehensive tool framework documentation
+- [Plugin Framework Reference](./docs/tools.md) - Comprehensive framework documentation
+- [Plugin Manifest Schema](./docs/plugin-manifest-schema.json) - JSON schema for manifest.json
+- [Guidelines](./GUIDELINES.md) - Framework development guidelines
## Core Interfaces
@@ -240,8 +281,9 @@ Conversation management interface:
1. Fork the repository
2. Create your feature branch
-3. Follow the [Creating Tools](./docs/CREATING_TOOLS.md) guide
-4. Ensure tests pass using \`deno test\`
+3. Follow the [Creating Plugins](./docs/CREATING_TOOLS.md) guide
+4. Follow the [Guidelines](./GUIDELINES.md) for framework development
+5. Ensure tests pass using \`deno test\`
5. Submit a pull request
## Testing
diff --git a/deno.jsonc b/deno.jsonc
index d9bfb69..ed4212f 100644
--- a/deno.jsonc
+++ b/deno.jsonc
@@ -6,8 +6,8 @@
".": "./mod.ts",
"./llm-tools": "./llm_tool.ts",
"./examples": "./examples/mod.ts",
- "./examples/open_in_browser": "./examples/open_in_browser.tool/tool.ts",
- "./examples/search_project": "./examples/search_project.tool/tool.ts"
+ "./examples/open-in-browser": "./examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts",
+ "./examples/search-project": "./examples/search-plugin.bbplugin/search-project.tool/tool.ts"
},
"tasks": {
"publish": "deno publish",
diff --git a/deno.lock b/deno.lock
index 882c76e..62f7953 100644
--- a/deno.lock
+++ b/deno.lock
@@ -13,8 +13,9 @@
"npm:ajv@8.17.1": "8.17.1",
"npm:common-tags@1.8.2": "1.8.2",
"npm:node-fetch@3.3.2": "3.3.2",
- "npm:open@*": "10.1.0",
+ "npm:open@*": "10.2.0",
"npm:open@10.1.0": "10.1.0",
+ "npm:open@10.2.0": "10.2.0",
"npm:preact@*": "10.25.3",
"npm:preact@10.22.0": "10.22.0",
"npm:preact@10.25.3": "10.25.3"
@@ -154,6 +155,15 @@
"is-wsl"
]
},
+ "open@10.2.0": {
+ "integrity": "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==",
+ "dependencies": [
+ "default-browser",
+ "define-lazy-prop",
+ "is-inside-container",
+ "wsl-utils"
+ ]
+ },
"preact@10.22.0": {
"integrity": "sha512-RRurnSjJPj4rp5K6XoP45Ui33ncb7e4H7WiOHVpjbkvqvA3U+N8Z6Qbo0AE6leGYBV66n8EhEaFixvIu3SkxFw=="
},
@@ -180,6 +190,12 @@
},
"web-streams-polyfill@3.3.3": {
"integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw=="
+ },
+ "wsl-utils@0.1.0": {
+ "integrity": "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==",
+ "dependencies": [
+ "is-wsl"
+ ]
}
},
"remote": {
diff --git a/docs/CREATING_TOOLS.md b/docs/CREATING_TOOLS.md
index ff4a762..979a322 100644
--- a/docs/CREATING_TOOLS.md
+++ b/docs/CREATING_TOOLS.md
@@ -1,53 +1,107 @@
-# Creating Tools for BB
+# Creating BB Plugins
-This guide provides comprehensive instructions for creating new tools in the BB ecosystem. It covers
-the entire process from planning to implementation and testing.
+This guide provides comprehensive instructions for creating new plugins for the Beyond Better (BB) ecosystem. Each plugin can contain one or more tools and/or datasources, packaged in a structured `.bbplugin` directory.
## Overview
-When creating a new tool:
-
-1. Use an existing tool as a template
-2. Follow established patterns and conventions
-3. Maintain consistent structure and style
-4. Implement comprehensive testing
+BB plugins use a structured directory format that enables:
+- Easy distribution and installation
+- Multiple tools and datasources in a single package
+- Clear metadata and versioning
+- OS-level file association for double-click installation
+
+**Note**: The standalone `.tool` directory structure is deprecated but still supported. All new development should use the `.bbplugin` structure.
+
+## Plugin Structure
+
+### Basic Plugin Package
+
+```
+your-plugin.bbplugin/
+├── manifest.json # Required: Plugin metadata
+├── your-tool.tool/ # Tool directory
+│ ├── tool.ts # Tool implementation
+│ ├── info.json # Tool metadata
+│ ├── formatter.browser.tsx # Browser formatting
+│ ├── formatter.console.ts # Console formatting
+│ └── tool.test.ts # Tool tests
+└── another-tool.tool/ # Additional tools (optional)
+ ├── tool.ts
+ ├── info.json
+ ├── formatter.browser.tsx
+ ├── formatter.console.ts
+ └── tool.test.ts
+```
+
+### Multi-Component Plugin
+
+```
+advanced-plugin.bbplugin/
+├── manifest.json # Required: Plugin metadata
+├── search-tool.tool/ # Tool component
+│ ├── tool.ts
+│ ├── info.json
+│ └── ...
+└── api-datasource.datasource/ # Datasource component (future support)
+ ├── datasource.ts
+ ├── info.json
+ └── ...
+```
## Step-by-Step Guide
-1. **Choose a Reference Tool**
- - Select an existing tool similar to your planned functionality
+1. **Choose a Reference Plugin**
+ - Select an existing plugin similar to your planned functionality
- Use it as a template throughout development
2. **Gather Information**
```typescript
- // Information Template
+ // Plugin Planning Template
{
- toolName: string; // Descriptive name
- description: string; // Brief purpose
- inputSchema: JSONSchema4; // Parameter definitions
- expectedOutput: string; // What tool returns
- requiredActions: string[]; // Main functionality
- errorScenarios: string[]; // Error handling cases
+ pluginName: string; // Plugin package name
+ version: string; // Semantic version
+ description: string; // Plugin purpose
+ author: string; // Creator name
+ license: string; // License type
+ tools: {
+ toolName: string; // Tool name
+ description: string; // Tool purpose
+ inputSchema: JSONSchema4; // Parameters
+ expectedOutput: string; // Return value
+ requiredActions: string[]; // Functionality
+ errorScenarios: string[]; // Error cases
+ }[];
+ datasources?: {...}[]; // Future datasource components
}
```
-3. **Create Tool Structure**
+3. **Create Plugin Package Structure**
+ ```bash
+ mkdir -p your-plugin.bbplugin/your-tool.tool
```
- your-tool/
- ├── tool.ts # Main tool implementation
- ├── info.json # Tool metadata and examples
- ├── formatter.browser.tsx # Browser-specific formatting
- ├── formatter.console.ts # Console-specific formatting
- └── tool.test.ts # Tool tests
+
+4. **Create Plugin Manifest** (`manifest.json`)
+ ```json
+ {
+ "name": "your-plugin",
+ "version": "1.0.0",
+ "author": "Your Name",
+ "description": "A collection of useful tools for...",
+ "license": "MIT",
+ "tools": ["your-tool.tool", "another-tool.tool"],
+ "datasources": [],
+ "bbVersion": ">=0.9.0"
+ }
```
+ See [Plugin Manifest Schema](#plugin-manifest-schema) for complete specification.
-4. **Create Tool Metadata**
+5. **Create Tool Metadata** (`your-tool.tool/info.json`)
```json
{
"name": "your_tool",
"description": "Detailed description of your tool...",
"version": "1.0.0",
- "author": "BB Team",
+ "author": "Your Name",
"license": "MIT",
"examples": [
{
@@ -60,7 +114,7 @@ When creating a new tool:
}
```
-5. **Implement Core Components**
+6. **Implement Core Components**
```typescript
import LLMTool, {
@@ -105,7 +159,7 @@ When creating a new tool:
}
```
-6. **Implement Formatters**
+7. **Implement Formatters**
Browser (formatter.browser.tsx):
```typescript
@@ -160,6 +214,166 @@ When creating a new tool:
}
```
+## Plugin Manifest Schema
+
+The `manifest.json` file is required at the root of every `.bbplugin` package. It provides metadata about the plugin and lists all included components.
+
+### Schema Definition
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "BB Plugin Manifest",
+ "type": "object",
+ "required": ["name", "version", "description", "tools"],
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Plugin package name (kebab-case recommended)",
+ "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+ "examples": ["my-plugin", "search-tools"]
+ },
+ "version": {
+ "type": "string",
+ "description": "Semantic version number",
+ "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
+ "examples": ["1.0.0", "2.1.0-beta.1"]
+ },
+ "author": {
+ "type": "string",
+ "description": "Plugin creator name or organization",
+ "examples": ["Your Name", "Your Organization"]
+ },
+ "description": {
+ "type": "string",
+ "description": "Brief description of plugin functionality",
+ "minLength": 10,
+ "maxLength": 500
+ },
+ "license": {
+ "type": "string",
+ "description": "License identifier (SPDX format recommended)",
+ "examples": ["MIT", "Apache-2.0", "GPL-3.0"]
+ },
+ "tools": {
+ "type": "array",
+ "description": "List of tool directories included in plugin",
+ "items": {
+ "type": "string",
+ "pattern": "^[a-z0-9_-]+\\.tool$",
+ "examples": ["search-tool.tool", "format-tool.tool"]
+ },
+ "minItems": 0
+ },
+ "datasources": {
+ "type": "array",
+ "description": "List of datasource directories included in plugin",
+ "items": {
+ "type": "string",
+ "pattern": "^[a-z0-9_-]+\\.datasource$",
+ "examples": ["api-datasource.datasource"]
+ },
+ "minItems": 0,
+ "default": []
+ },
+ "bbVersion": {
+ "type": "string",
+ "description": "Minimum BB version required (semver range)",
+ "examples": [">=0.9.0", "^1.0.0"],
+ "default": ">=0.9.0"
+ },
+ "homepage": {
+ "type": "string",
+ "format": "uri",
+ "description": "Plugin homepage or repository URL"
+ },
+ "repository": {
+ "type": "object",
+ "description": "Repository information",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": ["git", "svn", "hg"]
+ },
+ "url": {
+ "type": "string",
+ "format": "uri"
+ }
+ }
+ },
+ "keywords": {
+ "type": "array",
+ "description": "Keywords for plugin discovery",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+}
+```
+
+### Example Manifests
+
+**Simple Plugin with One Tool:**
+```json
+{
+ "name": "search-plugin",
+ "version": "1.0.0",
+ "author": "John Doe",
+ "description": "Advanced search capabilities for BB",
+ "license": "MIT",
+ "tools": ["search-tool.tool"],
+ "datasources": [],
+ "bbVersion": ">=0.9.0"
+}
+```
+
+**Multi-Tool Plugin:**
+```json
+{
+ "name": "dev-tools",
+ "version": "2.1.0",
+ "author": "Dev Team",
+ "description": "Collection of development utilities",
+ "license": "Apache-2.0",
+ "tools": [
+ "search-tool.tool",
+ "format-tool.tool",
+ "lint-tool.tool"
+ ],
+ "datasources": [],
+ "bbVersion": ">=1.0.0",
+ "homepage": "https://github.com/user/dev-tools",
+ "keywords": ["development", "utilities", "formatting"]
+}
+```
+
+**Plugin with Tools and Datasources:**
+```json
+{
+ "name": "api-integration",
+ "version": "1.5.0",
+ "author": "API Corp",
+ "description": "Tools and datasources for API integration",
+ "license": "MIT",
+ "tools": ["api-query.tool", "api-test.tool"],
+ "datasources": ["rest-api.datasource"],
+ "bbVersion": ">=0.9.0",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/apicorp/bb-api-integration"
+ }
+}
+```
+
+### Validation Requirements
+
+1. **Plugin Name**: Must be kebab-case, lowercase alphanumeric with hyphens
+2. **Version**: Must follow semantic versioning (major.minor.patch)
+3. **Component Lists**: All listed tools/datasources must exist as directories
+4. **Directory Names**: Must match the pattern in manifest exactly
+5. **BB Version**: Should specify minimum compatible version
+
## Tool Types and Considerations
### File Manipulation Tools
@@ -222,33 +436,103 @@ See [TESTING.md](./TESTING.md) for detailed testing guidelines. Key points:
3. Include usage examples
4. Document error scenarios
+## Plugin Distribution and Installation
+
+### Installation Methods
+
+1. **Double-Click Installation** (macOS/Windows)
+ - Users can double-click `.bbplugin` files
+ - OS file association opens BB DUI
+ - Installation dialog shows plugin details
+ - Plugin copied to configured directory
+ - Requires BB API restart to load
+
+2. **Manual Installation**
+ - Copy `.bbplugin` directory to plugin directory
+ - Default locations:
+ - macOS: `~/.config/bb/plugins`
+ - Windows: `%APPDATA%/bb/plugins`
+ - Linux: `~/.config/bb/plugins`
+ - Custom locations via `config.yaml`:
+ ```yaml
+ api:
+ userPluginDirectories:
+ - ./my-plugins
+ - /absolute/path/to/plugins
+ ```
+
+3. **Plugin Discovery**
+ - BB scans plugin directories on startup
+ - Loads tools from: `plugins/*.bbplugin/*.tool`
+ - Also supports legacy: `plugins/*.tool` (deprecated)
+ - Tools registered with LLM for use
+
+### Version Management
+
+- Plugin versions follow semantic versioning
+- BB detects version conflicts during installation
+- Warns on downgrades or duplicate versions
+- Users can choose to upgrade/replace existing plugins
+
+### Packaging for Distribution
+
+1. **Prepare Package**
+ - Ensure all files are present
+ - Validate manifest.json
+ - Test all tools locally
+ - Include README.md with usage instructions
+
+2. **Distribution Options**
+ - Direct file sharing (`.bbplugin` directory)
+ - Archive formats (`.zip`, `.tar.gz`)
+ - Version control repositories
+ - Future: BB plugin marketplace
+
+3. **Best Practices**
+ - Include comprehensive documentation
+ - Provide usage examples
+ - List dependencies and requirements
+ - Specify BB version compatibility
+ - Include license information
+
## Best Practices
-1. **Code Organization**
- - Keep related code together
+1. **Plugin Organization**
+ - Group related tools in a single plugin
+ - Use clear, descriptive plugin names
+ - Keep manifest.json accurate and complete
+ - Version plugins semantically
+ - Document all included components
+
+2. **Code Organization**
+ - Keep related code together within each tool
- Use clear file structure (tool.ts, info.json, formatters)
- - Follow naming conventions
- - Maintain consistent formatting
-
-2. **Implementation**
- - Follow existing patterns
- - Keep methods focused
- - Handle errors gracefully
- - Clean up resources
-
-3. **Testing**
- - Write comprehensive tests
- - Test edge cases
- - Test error scenarios
- - Maintain test consistency
-
-4. **Documentation**
- - Keep docs up to date
- - Include examples in info.json
- - Document errors
- - Explain complex logic
-
-5. **Formatting**
+ - Follow naming conventions (kebab-case for directories)
+ - Maintain consistent formatting across all tools
+ - Separate tool-specific types into types.ts
+
+3. **Implementation**
+ - Follow existing patterns from example tools
+ - Keep methods focused and single-purpose
+ - Handle errors gracefully with clear messages
+ - Clean up resources properly
+ - Consider performance implications
+
+4. **Testing**
+ - Write comprehensive tests for each tool
+ - Test edge cases and boundary conditions
+ - Test error scenarios thoroughly
+ - Maintain test consistency across plugin
+ - Test installation and discovery process
+
+5. **Documentation**
+ - Keep manifest.json and info.json up to date
+ - Include examples in tool info.json files
+ - Document errors and edge cases
+ - Explain complex logic with comments
+ - Provide plugin-level README with overview
+
+6. **Formatting**
- Use TOOL_TAGS_BROWSER for browser output
- Use TOOL_STYLES_CONSOLE for console output
- Use JSX fragments (<>...) for browser components
@@ -256,8 +540,70 @@ See [TESTING.md](./TESTING.md) for detailed testing guidelines. Key points:
- Provide clear labels and structure
- Handle success and error states consistently
+7. **Compatibility**
+ - Specify minimum BB version in manifest
+ - Test with target BB versions
+ - Avoid BB internal APIs unless necessary
+ - Handle version differences gracefully
+ - Document any version-specific features
+
+## Legacy Tool Structure (Deprecated)
+
+**Note**: The standalone `.tool` directory structure is deprecated. While BB still supports it for backward compatibility, all new development should use the `.bbplugin` structure.
+
+### Old Structure (Deprecated)
+```
+plugins/
+├── search-tool.tool/ # Standalone tool (deprecated)
+│ ├── tool.ts
+│ ├── info.json
+│ └── ...
+└── format-tool.tool/ # Another standalone tool (deprecated)
+ ├── tool.ts
+ └── ...
+```
+
+### New Structure (Current)
+```
+plugins/
+├── search-plugin.bbplugin/ # Plugin package (current)
+│ ├── manifest.json
+│ ├── search-tool.tool/
+│ │ ├── tool.ts
+│ │ └── ...
+│ └── format-tool.tool/
+│ ├── tool.ts
+│ └── ...
+└── other-plugin.bbplugin/ # Another plugin
+ ├── manifest.json
+ └── ...
+```
+
+### Migration Notes
+
+**Why Migrate?**
+- Improved organization and discoverability
+- Support for multiple components (tools + datasources)
+- Better version management
+- Enable double-click installation
+- Prepare for plugin marketplace
+- Future: digital signatures and security
+
+**Migration Steps:**
+1. Create new `.bbplugin` directory
+2. Move `.tool` directories into plugin directory
+3. Create `manifest.json` with metadata
+4. Test plugin discovery and loading
+5. Update distribution method
+
+**Backward Compatibility:**
+- BB continues to discover standalone `.tool` directories
+- No immediate migration required
+- Consider migration for new features and better UX
+
## See Also
- [README.md](../README.md) - Package overview
- [TESTING.md](./TESTING.md) - Testing guidelines
- [tools.md](./tools.md) - Tool reference
+- [Plugin Installation Guide](https://github.com/beyond-better/bb) - BB plugin installation documentation
diff --git a/docs/TESTING.md b/docs/TESTING.md
index d29eefe..c55152a 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -1,7 +1,7 @@
-# Testing Guidelines for BB Tools
+# Testing Guidelines for BB Plugins
-This document outlines testing requirements and best practices for the BB tools package. Following
-these guidelines ensures consistent quality and reliability across all tools.
+This document outlines testing requirements and best practices for BB plugins and tools. Following
+these guidelines ensures consistent quality and reliability across all plugin components.
## Core Principles
@@ -10,17 +10,21 @@ these guidelines ensures consistent quality and reliability across all tools.
- Maintain consistent structure and style
- Only modify what's necessary for new functionality
-2. **Test File Structure**
+2. **Plugin Structure**
```
- your-tool/
- ├── tool.ts # Main tool implementation
- ├── info.json # Tool metadata and examples
- ├── formatter.browser.tsx # Browser-specific formatting
- ├── formatter.console.ts # Console-specific formatting
- └── tool.test.ts # Tool tests
+ your-plugin.bbplugin/
+ ├── manifest.json # Plugin metadata
+ └── your-tool.tool/ # Tool directory
+ ├── tool.ts # Main tool implementation
+ ├── info.json # Tool metadata and examples
+ ├── formatter.browser.tsx # Browser-specific formatting
+ ├── formatter.console.ts # Console-specific formatting
+ └── tool.test.ts # Tool tests
```
3. **Test Coverage Requirements**
+ - Plugin manifest validation
+ - Tool discovery and loading
- Basic functionality
- Edge cases
- Error scenarios
diff --git a/docs/plugin-manifest-schema.json b/docs/plugin-manifest-schema.json
new file mode 100644
index 0000000..4bf1d8b
--- /dev/null
+++ b/docs/plugin-manifest-schema.json
@@ -0,0 +1,247 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "$id": "https://beyondbetter.dev/schemas/plugin-manifest.json",
+ "title": "BB Plugin Manifest",
+ "description": "Metadata schema for Beyond Better (.bbplugin) plugin packages",
+ "type": "object",
+ "required": ["name", "version", "description", "tools"],
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Plugin package name (kebab-case recommended)",
+ "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+ "minLength": 1,
+ "maxLength": 100,
+ "examples": [
+ "my-plugin",
+ "search-tools",
+ "dev-utilities"
+ ]
+ },
+ "version": {
+ "type": "string",
+ "description": "Semantic version number (major.minor.patch)",
+ "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
+ "examples": [
+ "1.0.0",
+ "2.1.0-beta.1",
+ "3.0.0+build.123"
+ ]
+ },
+ "author": {
+ "type": "string",
+ "description": "Plugin creator name or organization",
+ "minLength": 1,
+ "maxLength": 200,
+ "examples": [
+ "John Doe",
+ "Acme Corporation",
+ "Open Source Community"
+ ]
+ },
+ "description": {
+ "type": "string",
+ "description": "Brief description of plugin functionality",
+ "minLength": 10,
+ "maxLength": 500
+ },
+ "license": {
+ "type": "string",
+ "description": "License identifier (SPDX format recommended)",
+ "examples": [
+ "MIT",
+ "Apache-2.0",
+ "GPL-3.0",
+ "BSD-3-Clause",
+ "ISC"
+ ]
+ },
+ "tools": {
+ "type": "array",
+ "description": "List of tool directories included in this plugin",
+ "items": {
+ "type": "string",
+ "pattern": "^[a-z0-9_-]+\\.tool$",
+ "examples": [
+ "search-tool.tool",
+ "format-tool.tool",
+ "lint_checker.tool"
+ ]
+ },
+ "minItems": 0,
+ "uniqueItems": true
+ },
+ "datasources": {
+ "type": "array",
+ "description": "List of datasource directories included in this plugin (future support)",
+ "items": {
+ "type": "string",
+ "pattern": "^[a-z0-9_-]+\\.datasource$",
+ "examples": [
+ "api-datasource.datasource",
+ "db-connection.datasource"
+ ]
+ },
+ "minItems": 0,
+ "uniqueItems": true,
+ "default": []
+ },
+ "bbVersion": {
+ "type": "string",
+ "description": "Minimum Beyond Better version required (semver range)",
+ "examples": [
+ ">=0.9.0",
+ "^1.0.0",
+ ">=1.2.0 <2.0.0"
+ ],
+ "default": ">=0.9.0"
+ },
+ "homepage": {
+ "type": "string",
+ "format": "uri",
+ "description": "Plugin homepage or documentation URL",
+ "examples": [
+ "https://github.com/user/my-plugin",
+ "https://myplugin.dev"
+ ]
+ },
+ "repository": {
+ "type": "object",
+ "description": "Source code repository information",
+ "required": ["type", "url"],
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": ["git", "svn", "hg"],
+ "description": "Version control system type"
+ },
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Repository URL",
+ "examples": [
+ "https://github.com/user/repo.git",
+ "git+ssh://git@github.com/user/repo.git"
+ ]
+ },
+ "directory": {
+ "type": "string",
+ "description": "Directory path within monorepo (if applicable)",
+ "examples": [
+ "packages/my-plugin"
+ ]
+ }
+ }
+ },
+ "keywords": {
+ "type": "array",
+ "description": "Keywords for plugin discovery and search",
+ "items": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 50
+ },
+ "maxItems": 20,
+ "uniqueItems": true,
+ "examples": [
+ ["search", "indexing", "productivity"],
+ ["formatting", "code-style", "linting"],
+ ["api", "integration", "rest"]
+ ]
+ },
+ "bugs": {
+ "type": "object",
+ "description": "Bug tracking information",
+ "properties": {
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Bug tracker URL"
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "description": "Email address for bug reports"
+ }
+ }
+ },
+ "contributors": {
+ "type": "array",
+ "description": "List of plugin contributors",
+ "items": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Contributor name"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Contributor name"
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "description": "Contributor email"
+ },
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Contributor website/profile"
+ }
+ },
+ "required": ["name"]
+ }
+ ]
+ }
+ },
+ "funding": {
+ "oneOf": [
+ {
+ "type": "string",
+ "format": "uri",
+ "description": "Funding platform URL"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "Funding platform type",
+ "examples": ["github", "opencollective", "patreon", "ko-fi"]
+ },
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Funding page URL"
+ }
+ },
+ "required": ["url"]
+ },
+ {
+ "type": "array",
+ "description": "Multiple funding sources",
+ "items": {
+ "oneOf": [
+ {
+ "type": "string",
+ "format": "uri"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": { "type": "string" },
+ "url": { "type": "string", "format": "uri" }
+ },
+ "required": ["url"]
+ }
+ ]
+ }
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+}
diff --git a/docs/tools.md b/docs/tools.md
index 03d714a..9dcdc24 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -1,13 +1,24 @@
-# BB Tools Reference
+# BB Plugin Framework Reference
-This document provides a comprehensive reference for the BB tools framework, including tool types,
-interfaces, implementation patterns, and styling guidelines.
+This document provides a comprehensive reference for the BB plugin framework, including plugin structure,
+tool types, interfaces, implementation patterns, and styling guidelines.
-## Tool Framework Overview
+## Plugin Framework Overview
-The BB tools framework provides a structured way to create tools that can be used by AI assistants.
-Each tool:
+The BB plugin framework provides a structured way to create and distribute tools and datasources that can be used by AI assistants.
+### Plugin Structure
+
+Plugins are packaged as `.bbplugin` directories containing:
+- **manifest.json**: Required plugin metadata
+- **Tool components**: One or more `.tool` directories
+- **Datasource components**: Optional `.datasource` directories (future support)
+
+**Note**: Standalone `.tool` directories are deprecated but still supported for backward compatibility.
+
+### Tool Components
+
+Each tool within a plugin:
- Extends the `LLMTool` base class
- Implements specific interfaces
- Provides both browser and console formatting
diff --git a/examples/browser-plugin.bbplugin/manifest.json b/examples/browser-plugin.bbplugin/manifest.json
new file mode 100644
index 0000000..b8f30c3
--- /dev/null
+++ b/examples/browser-plugin.bbplugin/manifest.json
@@ -0,0 +1,11 @@
+{
+ "name": "browser-plugin",
+ "version": "1.0.0",
+ "author": "BB Team",
+ "description": "Browser integration tools for opening URLs and files in web browsers",
+ "license": "MIT",
+ "tools": ["open-in-browser.tool"],
+ "datasources": [],
+ "bbVersion": ">=0.9.0",
+ "keywords": ["browser", "url", "open", "web"]
+}
diff --git a/examples/open_in_browser.tool/formatter.browser.tsx b/examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.browser.tsx
similarity index 100%
rename from examples/open_in_browser.tool/formatter.browser.tsx
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.browser.tsx
diff --git a/examples/open_in_browser.tool/formatter.console.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.console.ts
similarity index 100%
rename from examples/open_in_browser.tool/formatter.console.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.console.ts
diff --git a/examples/open_in_browser.tool/info.json b/examples/browser-plugin.bbplugin/open-in-browser.tool/info.json
similarity index 100%
rename from examples/open_in_browser.tool/info.json
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/info.json
diff --git a/examples/open_in_browser.tool/tool.test.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/tool.test.ts
similarity index 100%
rename from examples/open_in_browser.tool/tool.test.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/tool.test.ts
diff --git a/examples/open_in_browser.tool/tool.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts
similarity index 93%
rename from examples/open_in_browser.tool/tool.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts
index eccff03..afedf4f 100644
--- a/examples/open_in_browser.tool/tool.ts
+++ b/examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts
@@ -33,7 +33,7 @@ import LLMTool, {
type LLMToolLogEntryFormattedResult,
type LLMToolRunResult,
} from 'jsr:@beyondbetter/tools';
-import open, { apps } from 'npm:open@10.1.0';
+import open, { apps } from 'npm:open@10.2.0';
import {
formatLogEntryToolResult as formatLogEntryToolResultBrowser,
@@ -82,7 +82,7 @@ export default class LLMToolOpenInBrowser extends LLMTool {
* These map to specific browser applications on the system.
* @private
*/
- private readonly predefinedBrowsers = ['chrome', 'firefox', 'edge', 'safari'] as const;
+ private readonly predefinedBrowsers = ['chrome', 'brave', 'firefox', 'edge', 'safari'] as const;
/**
* Maximum number of URLs that can be opened in one operation.
* Limits batch operations to prevent resource exhaustion.
@@ -113,13 +113,14 @@ export default class LLMToolOpenInBrowser extends LLMTool {
type: 'array',
items: { type: 'string' },
description:
- 'Array of URLs or file paths to open. Local paths will be converted to file:// URLs. Maximum of 6 URLs allowed.',
+ `Array of URLs or file paths to open. Local paths will be converted to file:// URLs. Maximum of ${this.maxUrls} URLs allowed.`,
maxItems: this.maxUrls,
},
browser: {
type: 'string',
- description:
- 'Browser to use. Can be one of the predefined browsers (chrome, firefox, edge, safari) or any other browser name. If not specified or "default", uses system default browser.',
+ description: `Browser to use. Can be one of the predefined browsers (${
+ this.predefinedBrowsers.join(', ')
+ }) or any other browser name. If not specified or "default", uses system default browser.`,
default: 'default',
},
},
@@ -178,6 +179,8 @@ export default class LLMToolOpenInBrowser extends LLMTool {
? apps.browser
: browser === 'chrome'
? apps.chrome
+ : browser === 'brave'
+ ? apps.brave
: browser === 'firefox'
? apps.firefox
: browser === 'edge'
diff --git a/examples/open_in_browser.tool/types.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/types.ts
similarity index 100%
rename from examples/open_in_browser.tool/types.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/types.ts
diff --git a/examples/mod.ts b/examples/mod.ts
index 03d527f..946fdf2 100644
--- a/examples/mod.ts
+++ b/examples/mod.ts
@@ -1,10 +1,10 @@
/**
- * Example tools demonstrating BB Tools framework usage.
- * Provides reference implementations of common tool patterns.
+ * Example plugins demonstrating BB Plugin framework usage.
+ * Provides reference implementations of plugin structure and common tool patterns.
*
- * Available Tools:
- * - SearchProjectTool: Search project files by content and metadata
- * - LLMToolOpenInBrowser: Open URLs and local files in web browsers
+ * Available Plugins:
+ * - search-plugin: Contains SearchProjectTool for searching project files
+ * - browser-plugin: Contains LLMToolOpenInBrowser for opening URLs in browsers
*
* @example
* ```ts
@@ -22,11 +22,14 @@
* }, projectEditor);
* ```
*
+ * Note: Example plugins use the new .bbplugin structure with manifest.json.
+ * Legacy standalone .tool directories are deprecated.
+ *
* @module
*/
-export { default as SearchProjectTool } from './search_project.tool/tool.ts';
-export type { SearchProjectInput } from './search_project.tool/tool.ts';
+export { default as SearchProjectTool } from './search-plugin.bbplugin/search-project.tool/tool.ts';
+export type { SearchProjectInput } from './search-plugin.bbplugin/search-project.tool/tool.ts';
-export { default as LLMToolOpenInBrowser } from './open_in_browser.tool/tool.ts';
-export type { LLMToolOpenInBrowserInput } from './open_in_browser.tool/types.ts';
+export { default as LLMToolOpenInBrowser } from './browser-plugin.bbplugin/open-in-browser.tool/tool.ts';
+export type { LLMToolOpenInBrowserInput } from './browser-plugin.bbplugin/open-in-browser.tool/types.ts';
diff --git a/examples/search-plugin.bbplugin/manifest.json b/examples/search-plugin.bbplugin/manifest.json
new file mode 100644
index 0000000..b4c5dcf
--- /dev/null
+++ b/examples/search-plugin.bbplugin/manifest.json
@@ -0,0 +1,11 @@
+{
+ "name": "search-plugin",
+ "version": "1.0.0",
+ "author": "BB Team",
+ "description": "Project search and content discovery tools for Beyond Better",
+ "license": "MIT",
+ "tools": ["search-project.tool"],
+ "datasources": [],
+ "bbVersion": ">=0.9.0",
+ "keywords": ["search", "project", "files", "content"]
+}
diff --git a/examples/search_project.tool/README.md b/examples/search-plugin.bbplugin/search-project.tool/README.md
similarity index 64%
rename from examples/search_project.tool/README.md
rename to examples/search-plugin.bbplugin/search-project.tool/README.md
index 4f79187..353827e 100644
--- a/examples/search_project.tool/README.md
+++ b/examples/search-plugin.bbplugin/search-project.tool/README.md
@@ -1,12 +1,16 @@
# Search Project Tool Example
-This example demonstrates how to create a tool using the BB Tools framework. It implements a file
-search tool that can search project files by content, name, date, and size.
+This example demonstrates how to create a plugin and tool using the BB Plugin framework. It implements a file
+search tool packaged within the `search-plugin.bbplugin` plugin that can search project files by content, name, date, and size.
+
+**Plugin Structure**: This tool is part of the `search-plugin` plugin package, demonstrating the recommended `.bbplugin` structure with manifest.json.
## Overview
The search project tool shows how to:
+- Structure a plugin using the `.bbplugin` format
+- Create a manifest.json for plugin metadata
- Implement the LLMTool base class
- Use IProjectEditor and IConversationInteraction interfaces
- Create browser and console formatters
@@ -14,15 +18,18 @@ The search project tool shows how to:
## Implementation
-### Tool Structure
+### Plugin Structure
```
-search_project/
-├── mod.ts # Main tool implementation
-├── formatter.browser.tsx # Browser formatting
-├── formatter.console.ts # Console formatting
-├── mod.test.ts # Tests
-└── README.md # Documentation
+search-plugin.bbplugin/
+├── manifest.json # Plugin metadata (required)
+└── search-project.tool/
+ ├── tool.ts # Main tool implementation
+ ├── formatter.browser.tsx # Browser formatting
+ ├── formatter.console.ts # Console formatting
+ ├── info.json # Tool metadata
+ ├── tool.test.ts # Tests
+ └── README.md # Documentation
```
### Key Features
@@ -48,11 +55,11 @@ search_project/
## Usage
```typescript
-import { SearchProjectTool } from '@beyondbetter/tools/examples/search_project';
+import { SearchProjectTool } from '@beyondbetter/tools/examples';
// Create tool instance
const tool = new SearchProjectTool(
- 'search_project',
+ 'search-project',
'Search project files',
{},
{ async: true },
@@ -63,7 +70,7 @@ const result = await tool.runTool(
conversationInteraction,
{
id: 'tool-use-1',
- name: 'search_project',
+ name: 'search-project',
toolInput: {
filePattern: '*.ts',
contentPattern: 'function',
@@ -74,6 +81,18 @@ const result = await tool.runTool(
);
```
+## Plugin Installation
+
+```bash
+# Copy plugin to BB plugins directory
+cp -r search-plugin.bbplugin ~/.config/bb/plugins/
+
+# Or double-click search-plugin.bbplugin (macOS/Windows)
+# BB will show installation dialog
+
+# Restart BB API to load the plugin
+```
+
## Implementation Details
### Input Validation
@@ -105,7 +124,7 @@ export function formatLogEntryToolUse(
): LLMToolLogEntryFormattedResult {
// ... format using JSX
return {
- title: tags.content.title('Tool Input', 'search_project'),
+ title: tags.content.title('Tool Input', 'search-project'),
content: ...
,
preview: 'Preview text',
};
@@ -120,7 +139,7 @@ export function formatLogEntryToolUse(
): LLMToolLogEntryFormattedResult {
// ... format using ANSI styles
return {
- title: styles.content.title('Tool Input', 'search_project'),
+ title: styles.content.title('Tool Input', 'search-project'),
content: '...',
preview: 'Preview text',
};
@@ -182,6 +201,7 @@ Deno.test('SearchProjectTool - Console formatter', () => {
## See Also
-- [Tool Creation Guide](../../docs/CREATING_TOOLS.md)
-- [Testing Guide](../../docs/TESTING.md)
-- [Tool Reference](../../docs/tools.md)
+- [Plugin Creation Guide](../../../docs/CREATING_TOOLS.md)
+- [Testing Guide](../../../docs/TESTING.md)
+- [Plugin Framework Reference](../../../docs/tools.md)
+- [Plugin Manifest Schema](../../../docs/plugin-manifest-schema.json)
diff --git a/examples/search_project.tool/formatter.browser.tsx b/examples/search-plugin.bbplugin/search-project.tool/formatter.browser.tsx
similarity index 100%
rename from examples/search_project.tool/formatter.browser.tsx
rename to examples/search-plugin.bbplugin/search-project.tool/formatter.browser.tsx
diff --git a/examples/search_project.tool/formatter.console.ts b/examples/search-plugin.bbplugin/search-project.tool/formatter.console.ts
similarity index 100%
rename from examples/search_project.tool/formatter.console.ts
rename to examples/search-plugin.bbplugin/search-project.tool/formatter.console.ts
diff --git a/examples/search_project.tool/info.json b/examples/search-plugin.bbplugin/search-project.tool/info.json
similarity index 100%
rename from examples/search_project.tool/info.json
rename to examples/search-plugin.bbplugin/search-project.tool/info.json
diff --git a/examples/search_project.tool/tool.test.ts b/examples/search-plugin.bbplugin/search-project.tool/tool.test.ts
similarity index 100%
rename from examples/search_project.tool/tool.test.ts
rename to examples/search-plugin.bbplugin/search-project.tool/tool.test.ts
diff --git a/examples/search_project.tool/tool.ts b/examples/search-plugin.bbplugin/search-project.tool/tool.ts
similarity index 100%
rename from examples/search_project.tool/tool.ts
rename to examples/search-plugin.bbplugin/search-project.tool/tool.ts
diff --git a/llm_tool.ts b/llm_tool.ts
index 1b883b4..72e254b 100644
--- a/llm_tool.ts
+++ b/llm_tool.ts
@@ -142,6 +142,38 @@ export interface LLMToolLogEntryFormattedResult {
preview: string | JSX.Element;
}
+export interface LLMToolMetadata {
+ toolId: string;
+ name: string;
+ version: string;
+ protocolType: 'bb' | 'mcp';
+ loadedFrom: 'builtin' | 'plugin' | 'mcp';
+ author: string;
+ license: string;
+ description: string;
+ purpose: string;
+ path?: string; // is set by code, not part of manifest
+ toolSets?: string | string[]; //defaults to 'core'
+ category?: string | string[];
+ capabilities?: string | string[];
+ enabled?: boolean; //defaults to true
+ mutates?: boolean; //defaults to true
+ deprecated?: boolean; //defaults to false
+ replacedBy?: string; //when deprecated is true
+ error?: string;
+ config?: unknown;
+ mcpData?: Record; //LLMToolMCPConfig
+ pluginData?: {
+ pluginName: string;
+ version: string;
+ author: string;
+ description: string;
+ license: string;
+ bbVersion: string;
+ };
+ examples?: Array<{ description: string; input: unknown }>;
+}
+
/**
* Base class for all LLM tools in the BB Tools Framework.
* Provides core functionality for input validation, execution, and result formatting.
@@ -187,12 +219,19 @@ export interface LLMToolLogEntryFormattedResult {
* ```
*/
abstract class LLMTool {
+ public toolId: string;
+ public features: LLMToolFeatures = {};
+
constructor(
public name: string,
public description: string,
public toolConfig: LLMToolConfig,
- public features: LLMToolFeatures = {},
- ) {}
+ public metadata: LLMToolMetadata,
+ ) {
+ this.toolId = metadata.toolId || `${metadata.loadedFrom || 'builtin'}:${metadata.name}`;
+ this.features = { mutates: metadata.mutates || false };
+ //logger.info(`LLMTool: Constructing tool ${name}`);
+ }
// deno-lint-ignore require-await
public async init(): Promise {
diff --git a/mod.ts b/mod.ts
index baad904..9f54e45 100644
--- a/mod.ts
+++ b/mod.ts
@@ -105,6 +105,7 @@ export type {
LLMToolFormatterDestination,
LLMToolInputSchema,
LLMToolLogEntryFormattedResult,
+ LLMToolMetadata,
LLMToolRunBbResponse,
LLMToolRunBbResponseData,
LLMToolRunResult,