@tencent-ai/codebuddy-code 2.67.0-next.ed1b89f.20260329 → 2.68.0

package/dist/web-ui/docs/en/cli/plugin-marketplaces.md

@@ -0,0 +1,534 @@
+# Plugin Marketplaces
+
+A plugin marketplace is a plugin directory file used to distribute and manage CodeBuddy extensions. It is a JSON-formatted configuration file that lists available plugins and their source information.
+
+## Core Features
+
+- **Centralized Discovery**: Browse plugins from multiple sources in one place
+- **Version Management**: Automatically track and update plugin versions
+- **Auto-Update**: Support enabling auto-update to periodically sync marketplace content
+- **Team Distribution**: Share required plugins within organizations
+- **Flexible Sources**: Support for Git repositories, GitHub repositories, local paths, and HTTP URLs
+
+## Using Plugin Marketplaces
+
+### Prerequisites
+
+- CodeBuddy installed and running
+- Basic understanding of JSON file format
+- For creating a marketplace: Git repository or local development environment
+
+### Adding a Plugin Marketplace
+
+#### 1. Add a GitHub Marketplace
+
+```bash
+/plugin marketplace add owner/repo
+```
+
+The repository must contain a `.codebuddy-plugin/marketplace.json` file.
+
+#### 2. Add a Git Repository Marketplace
+
+```bash
+# HTTPS format
+/plugin marketplace add https://gitlab.com/company/plugins.git
+
+# SSH format (git@)
+/plugin marketplace add git@gitlab.com:company/plugins.git
+
+# .git suffix format
+/plugin marketplace add https://example.com/repo.git
+```
+
+#### 3. Add a Local Marketplace (for development)
+
+```bash
+# Add a local directory containing .codebuddy-plugin/marketplace.json
+/plugin marketplace add ./my-marketplace
+
+# Directly add a marketplace.json file path
+/plugin marketplace add ./path/to/marketplace.json
+```
+
+#### 4. Add an HTTP Marketplace
+
+```bash
+# Add a remote marketplace.json via URL
+/plugin marketplace add https://url.of/marketplace.json
+```
+
+### Installing Plugins from a Marketplace
+
+```bash
+# Install from a known marketplace
+/plugin install plugin-name@marketplace-name
+
+# Interactively browse available plugins
+/plugin
+```
+
+### Verifying Marketplace Installation
+
+1. **List Marketplaces**: Run `/plugin marketplace list` to confirm the marketplace was added
+2. **Browse Plugins**: Use `/plugin` to view available plugins in the marketplace
+3. **Test Installation**: Try installing a plugin to verify the marketplace is working properly
+
+## Team Configuration
+
+### Automatically Install Team Marketplaces
+
+Configure in `.codebuddy/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "team-tools": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/codebuddy-plugins"
+      }
+    },
+    "project-specific": {
+      "source": {
+        "source": "git",
+        "url": "https://git.company.com/project-plugins.git"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "plugin-a@team-tools": true,
+    "plugin-b@team-tools": true
+  }
+}
+```
+
+When team members start CodeBuddy, the system automatically installs these marketplaces and the plugins specified in the `enabledPlugins` field.
+
+### Automatic Installation Flow
+
+1. **Startup Detection**: CodeBuddy automatically detects the configuration file on startup
+2. **Marketplace Installation**: Automatically installs marketplaces from `extraKnownMarketplaces` that are not yet installed
+3. **Plugin Installation**: Automatically installs enabled plugins from `enabledPlugins` that are not yet installed
+4. **Background Execution**: The installation process executes asynchronously in the background without blocking the startup flow
+5. **Logging**: The installation process logs detailed information, viewable with `--debug`
+
+## Creating Your Own Marketplace
+
+### Prerequisites for Creation
+
+- Git repository (GitHub, GitLab, or other git hosting service)
+- Understanding of JSON file format
+- One or more plugins to distribute
+
+### Creating the Marketplace File
+
+Create `.codebuddy-plugin/marketplace.json` in the repository root:
+
+```json
+{
+  "name": "company-tools",
+  "owner": {
+    "name": "DevTools Team",
+    "email": "[email protected]"
+  },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "source": "./plugins/formatter",
+      "description": "Automatic code formatting on save",
+      "version": "2.1.0"
+    },
+    {
+      "name": "deployment-tools",
+      "source": {
+        "source": "github",
+        "repo": "company/deploy-plugin"
+      },
+      "description": "Deployment automation tools"
+    }
+  ]
+}
+```
+
+### Marketplace Schema
+
+#### Required Fields
+
+| Field | Type | Description |
+|------|------|------|
+| name | string | Marketplace identifier (kebab-case, no spaces) |
+| owner | object | Marketplace maintainer information |
+| plugins | array | List of available plugins |
+
+#### Optional Metadata Fields
+
+| Field | Type | Description |
+|------|------|------|
+| description | string | Brief marketplace description |
+| version | string | Marketplace version |
+
+### Plugin Entry Configuration
+
+#### Required Fields
+
+| Field | Type | Description |
+|------|------|------|
+| name | string | Plugin identifier (kebab-case, no spaces) |
+| source | string/object | Plugin source location |
+| description | string | Brief plugin description |
+
+#### Optional Metadata Fields
+
+| Field | Type | Description |
+|------|------|------|
+| version | string | Plugin version |
+| author | object | Plugin author information |
+| homepage | string | Plugin homepage or documentation URL |
+| repository | string | Source code repository URL |
+| license | string | SPDX license identifier (e.g., MIT, Apache-2.0) |
+| keywords | array | Tags for plugin discovery and categorization |
+| category | string | Plugin category |
+| strict | boolean | Require plugin.json in plugin folder (default: true) |
+
+#### Component Configuration Fields
+
+| Field | Type | Description |
+|------|------|------|
+| commands | string/array | Custom path to command files or directories |
+| agents | string/array | Custom path to agent files |
+| skills | string/array | Custom path to skill files |
+| hooks | string/object | Custom hooks configuration or hooks file path |
+| mcpServers | string/object | MCP server configuration or MCP config path |
+
+**About the strict field**:
+
+- `strict: true` (default): Plugin must contain a `plugin.json` manifest file, marketplace fields supplement these values
+- `strict: false`: `plugin.json` is optional. If missing, the marketplace entry serves as the complete plugin manifest
+
+### Plugin Source Types
+
+#### 1. Relative Path (Local)
+
+For plugins in the same repository:
+
+```json
+{
+  "name": "my-plugin",
+  "source": "./plugins/my-plugin",
+  "description": "My local plugin"
+}
+```
+
+#### 2. GitHub Repository
+
+```json
+{
+  "name": "github-plugin",
+  "source": {
+    "source": "github",
+    "repo": "owner/plugin-repo"
+  },
+  "description": "Plugin from GitHub"
+}
+```
+
+#### 3. Git URL
+
+```json
+{
+  "name": "git-plugin",
+  "source": {
+    "source": "url",
+    "url": "https://gitlab.com/team/plugin.git"
+  },
+  "description": "Plugin from Git URL"
+}
+```
+
+### Advanced Plugin Entry Example
+
+```json
+{
+  "name": "enterprise-tools",
+  "source": {
+    "source": "github",
+    "repo": "company/enterprise-plugin"
+  },
+  "description": "Enterprise workflow automation tools",
+  "version": "2.1.0",
+  "author": {
+    "name": "Enterprise Team",
+    "email": "[email protected]"
+  },
+  "homepage": "https://docs.company.com/plugins/enterprise-tools",
+  "repository": "https://github.com/company/enterprise-plugin",
+  "license": "MIT",
+  "keywords": ["enterprise", "workflow", "automation"],
+  "category": "productivity",
+  "commands": [
+    "./commands/core/",
+    "./commands/enterprise/",
+    "./commands/experimental/preview.md"
+  ],
+  "agents": [
+    "./agents/security-reviewer.md",
+    "./agents/compliance-checker.md"
+  ],
+  "skills": [
+    "./skills/deployment.md",
+    "./skills/monitoring.md"
+  ],
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/validate.sh"
+        }]
+      }
+    ]
+  },
+  "mcpServers": {
+    "enterprise-db": {
+      "command": "${CODEBUDDY_PLUGIN_ROOT}/servers/db-server",
+      "args": ["--config", "${CODEBUDDY_PLUGIN_ROOT}/config.json"]
+    }
+  },
+  "strict": false
+}
+```
+
+**Note**: `${CODEBUDDY_PLUGIN_ROOT}` is an environment variable that resolves to the plugin's installation directory.
+
+## Hosting and Distributing Marketplaces
+
+### 1. Hosting on GitHub (Recommended)
+
+**Steps**:
+
+1. Create a repository: Set up a new repository for the marketplace
+2. Add the marketplace file: Create `.codebuddy-plugin/marketplace.json` and define plugins
+3. Share with your team: Team members add it using `/plugin marketplace add owner/repo`
+
+**Advantages**: Built-in version control, issue tracking, and team collaboration features
+
+### 2. Hosting on Other Git Services
+
+Any git hosting service can be used for marketplace distribution. For example, using GitLab:
+
+```bash
+/plugin marketplace add https://gitlab.com/company/plugins.git
+```
+
+### 3. Hosting via HTTP URL
+
+You can host the marketplace.json file on any HTTP(S) server:
+
+```bash
+/plugin marketplace add https://example.com/path/to/marketplace.json
+```
+
+### 4. Using Local Marketplaces for Development
+
+Test marketplaces locally before distribution:
+
+```bash
+# Add a local marketplace for testing
+/plugin marketplace add ./my-local-marketplace
+
+# Test plugin installation
+/plugin install test-plugin@my-local-marketplace
+```
+
+## Marketplace Management Operations
+
+### List Known Marketplaces
+
+```bash
+/plugin marketplace list
+```
+
+Displays all configured marketplaces along with their sources and status.
+
+### Update Marketplace Metadata
+
+```bash
+/plugin marketplace update marketplace-name
+```
+
+Refreshes the plugin list and metadata from the marketplace source.
+
+### Remove a Marketplace
+
+```bash
+/plugin marketplace remove marketplace-name
+```
+
+Removes the marketplace from configuration.
+
+**⚠️ Warning**: Removing a marketplace will uninstall all plugins installed from it.
+
+### Managing Auto-Updates
+
+You can enable auto-update functionality for marketplaces, where CodeBuddy automatically checks and updates enabled marketplaces on startup.
+
+**How to Enable**:
+
+1. Run the `/plugin` command to enter plugin management interface
+2. Select "Marketplaces" to view the marketplace list
+3. Select the marketplace you want to configure
+4. Select "Enable auto-update" or "Disable auto-update" to toggle the status
+
+**Auto-Update Mechanism**:
+
+- Executed with a 5-second delay on startup, does not affect main flow
+- Only updates marketplaces that haven't been updated in over 24 hours
+- Updates between multiple marketplaces are spaced 2 seconds apart to avoid resource contention
+- Update failures do not affect other marketplaces, errors are logged
+
+
+## Implementation Details
+
+### Marketplace Types
+
+CodeBuddy supports the following marketplace types:
+
+1. **Directory (Local Directory)**: Load plugins from the local filesystem
+2. **GitHub**: Clone and update plugins from GitHub repositories
+3. **Git**: Clone and update plugins from any Git repository
+4. **URL (HTTP)**: Download marketplace.json from HTTP(S) URLs
+
+### Marketplace Factory Pattern
+
+The `MarketplaceFactory` creates different marketplace instances based on configuration:
+
+```typescript
+// Create the corresponding marketplace instance based on source type
+switch (sourceType) {
+    case MarketplaceType.Directory:
+        marketplace = new DirectoryMarketplace();
+        break;
+    case MarketplaceType.Github:
+    case MarketplaceType.Git:
+        marketplace = new GithubMarketplace();
+        break;
+    case MarketplaceType.URL:
+        marketplace = new HttpMarketplace();
+        break;
+    default:
+        marketplace = new BaseMarketplace();
+        break;
+}
+```
+
+### Installation Flow
+
+1. **Parse Source**: Determine marketplace type based on input string (local path, GitHub repo, Git URL, HTTP URL)
+2. **Download/Clone**: Download or clone marketplace content based on marketplace type
+3. **Read Manifest**: Parse the `.codebuddy-plugin/marketplace.json` file
+4. **Save Configuration**: Save marketplace information to local storage
+5. **Update Cache**: Refresh plugin cache and marketplace list
+
+### Plugin Installers
+
+CodeBuddy uses plugin installers (PluginInstaller) to handle different plugin source types:
+
+- **Local Installer**: Handles relative path plugins
+- **Git Installer**: Handles GitHub and Git URL plugins
+
+Each installer implements the following methods:
+
+- `support(source)`: Determine if this plugin source is supported
+- `isInstalled(plugin, targetDir)`: Check if the plugin is already installed
+- `install(plugin, targetDir)`: Install the plugin
+- `update(plugin, installedPath)`: Update the plugin
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Marketplace Fails to Load
+
+**Symptoms**: Cannot add marketplace or cannot see its plugins
+
+**Solutions**:
+
+- Verify the marketplace URL is accessible
+- Check that `.codebuddy-plugin/marketplace.json` exists at the specified path
+- Ensure JSON syntax is valid
+- For private repositories, confirm you have access permissions
+
+#### 2. Plugin Installation Fails
+
+**Symptoms**: Marketplace displays but plugin installation fails
+
+**Solutions**:
+
+- Verify the plugin source URL is accessible
+- Check that the plugin directory contains required files
+- For GitHub sources, ensure the repository is public or you have access
+- Manually test the plugin source by cloning/downloading
+
+#### 3. Git Operations Fail
+
+**Symptoms**: Errors when cloning or pulling repositories
+
+**Solutions**:
+
+- Ensure Git is installed and available in the command line
+- Check network connection and proxy settings
+- Verify Git credentials are configured correctly
+- Use the `--debug` flag to view detailed logs
+
+### Debugging Tips
+
+1. **Enable Debug Logging**:
+
+```bash
+codebuddy --debug
+```
+
+2. **Manually Verify Marketplace File**:
+
+```bash
+# Check marketplace.json format
+cat .codebuddy-plugin/marketplace.json | jq
+```
+
+3. **Test Git Clone**:
+
+```bash
+# Manually test if Git clone succeeds
+git clone https://github.com/owner/repo.git /tmp/test-clone
+```
+
+## Next Steps
+
+### For Marketplace Users
+
+- Discover community marketplaces: Search for CodeBuddy plugin collections on GitHub
+- Contribute feedback: Report issues and suggest improvements to marketplace maintainers
+- Share useful marketplaces: Help your team discover valuable plugin collections
+
+### For Marketplace Creators
+
+- Build plugin collections: Create themed marketplaces around specific use cases
+- Establish versioning: Implement clear versioning and update strategies
+- Community engagement: Gather feedback and maintain an active marketplace community
+- Documentation: Provide clear README files explaining marketplace contents
+
+### For Organizations
+
+- Private marketplaces: Set up internal marketplaces for proprietary tools
+- Governance policies: Establish plugin approval and security review guidelines
+- Training resources: Help teams effectively discover and adopt useful plugins
+
+## Related Resources
+
+- [Plugin System](./plugins.md) - Plugin system overview
+- [Skills System](./skills.md) - Creating and using skills
+- [Slash Commands](./slash-commands.md) - Creating custom commands
+- [Hooks](./hooks.md) - Creating event hooks
+- [Settings](./settings.md) - Plugin configuration options