# 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
