From b7fae4a325d59e620d95482d477b5c1193ef1b68 Mon Sep 17 00:00:00 2001 From: NamesMT Date: Tue, 6 May 2025 06:55:33 +0000 Subject: [PATCH] chore(cline_docs/marketplace): align with `Roo-Code-Marketplace` --- .../user-guide/05-adding-packages.md | 184 +++++++----------- .../user-guide/06-adding-custom-sources.md | 71 ++----- 2 files changed, 81 insertions(+), 174 deletions(-) diff --git a/cline_docs/marketplace/user-guide/05-adding-packages.md b/cline_docs/marketplace/user-guide/05-adding-packages.md index c9ed4a1d6d..55ebd13e37 100644 --- a/cline_docs/marketplace/user-guide/05-adding-packages.md +++ b/cline_docs/marketplace/user-guide/05-adding-packages.md @@ -1,126 +1,75 @@ -# Adding Packages to the Marketplace +## Item Structure, Metadata, and Features -This guide explains how to create and contribute your own packages to the Roo Code Marketplace. By following these steps, you can share your work with the community and help expand the ecosystem. +### Overview -## Package Structure and Metadata - -Each package in the Marketplace requires specific metadata files and follows a consistent directory structure. +- Every component on the registry is an `item`. +- An `item` can be of type: `mcp`, `mode`, `prompt`, `package` +- Each item apart from `package` is a singular object, i.e: one mode, one mcp server. +- A `package` contains multiple other `item`s + - All internal sub-items of a `package` is contained in the binary on the `package` item metadata itself. +- Each `item` requires specific metadata files and follows a consistent directory structure. ### Directory Structure -The basic structure for a package is: +The `registry` structure could be the root or placed in a `registry` directory of any `git` repository, a sample structure for a registry is: ``` -package-name/ -├── metadata.en.yml # Required metadata file (English) -├── metadata.fr.yml # Optional localized metadata (French) -├── README.md # Documentation for the package -├── modes/ # Directory for mode components -│ └── my-mode/ +registry/ +├── metadata.en.yml # Required metadata for the registry +│ +├── modes/ # `mode` items +│ └── a-mode-name/ │ └── metadata.en.yml -├── mcp/ # Directory for MCP server components -│ └── my-server/ -│ └── metadata.en.yml -└── prompts/ # Directory for prompt components - └── my-prompt/ - └── metadata.en.yml +├── mcps/ # `mcp` items +├── prompts/ # `prompt` items +│ +└── packages/ # `package` items + └── a-package-name/ + ├── metadata.en.yml # Required metadata + ├── metadata.fr.yml # Optional localized metadata (French) + ├── modes/ # `a-package-name`'s internal `mode` items + │ └── my-mode/ + │ └── metadata.en.yml + ├── mcps/ # `a-package-name`'s internal `mcp` items + │ └── my-server/ + │ └── metadata.en.yml + └── prompts/ # `a-package-name`'s internal `prompt` items + └── my-prompt/ + └── metadata.en.yml ``` ### Metadata File Format Metadata files use YAML format and must include specific fields: +#### `registry`: + +```yaml +name: "My Registry" +description: "A concise description for your registry" +version: "0.0.0" +author: "your name" # optional +authorUrl: "http://your.profile.url/" # optional +``` + +#### `item`: + ```yaml name: "My Package" -description: "A detailed description of what this package does" -version: "1.0.0" +description: "A concise description for your package" +version: "0.0.0" type: "package" # One of: package, mode, mcp, prompt +sourceUrl: "https://url.to/source-repository" # Optional +binaryUrl: "https://url.to/binary.zip" +binaryHash: "SHA256-of-binary" +binarySource: "https://proof.of/source" # Optional, proof-of-source for the binary (tag/hash reference, build job, etc) tags: - tag1 - tag2 -items: # Only for packages AND when a subcomponent isn't located in the packages directory tree - - type: "prompt" - path: "../shared-prompts/data-analysis" # Reference to component outside package directory author: "your name" # optional -authorUrl: "http://your.profile.url/" #optional +authorUrl: "http://your.profile.url/" # optional ``` -### Package Example in Source Tree - -Here's how a package might look in the actual source tree: - -``` -Roo-Code-Marketplace/ -├── shared-prompts/ # Shared prompts directory -│ └── data-analysis/ -│ └── metadata.en.yml -│ -└── packages/ - └──data-toolkit/ # Your package directory - ├── metadata.en.yml # Package metadata - ├── metadata.fr.yml # Localized metadata - ├── README.md # Documentation - ├── modes/ # Modes directory - │ └── data-analyst/ - │ └── metadata.en.yml - └── mcp/ # MCP servers directory - └── data-processor/ - └── metadata.en.yml -``` - -### Required Fields - -- **name**: A clear, descriptive name for your component -- **description**: A detailed explanation of what your component does -- **version**: Semantic version number (e.g., "1.0.0") -- **type**: Component type (one of: "package", "mode", "mcp", "prompt") -- **tags**: (Optional) Array of relevant tags for filtering -- **items**: (Only for `package`) Array of subcomponents with their type and path - when the path is not in the packages directory - tree -- **author**: Your name -- **authorUrl**: A proile Url that you want people to see. GitHub profile, or linked-in profile for example -- **sourceUrl**: optional destination Url to your item's source if you haven't included it directly in the Marketplace. - -### The Items Array and External References - -The `items` array in a package's metadata serves only one important purposes: - -**External Component References**: It allows referencing components that exist outside the package's directory tree. - -Components that are within the package's directory tree are implicitly included and will be found at runtime. - -#### Referencing External Components - -You can reference components from anywhere in the repository by using relative paths: - -```yaml -items: - # Component within the package directory - - type: "mode" - path: "modes/my-mode" - - # Component outside the package directory (using relative path) - - type: "prompt" - path: "../shared-prompts/data-analysis" - - # Component from a completely different part of the repository - - type: "mcp" - path: "../../other-category/useful-server" -``` - -This allows you to: - -- Create shared components that can be used by multiple packages -- Organize components logically while maintaining package relationships -- Reference existing components without duplicating them - -#### How It Works - -- The `path` is relative to the package's directory -- The Marketplace resolves these paths when loading the package -- Components referenced this way appear as part of the package in the UI -- The same component can be included in multiple packages - ### Localization Support You can provide metadata in multiple languages by using locale-specific files: @@ -133,6 +82,15 @@ You can provide metadata in multiple languages by using locale-specific files: - The English locale (`metadata.en.yml`) is required as a fallback - Files without a locale code (e.g., just `metadata.yml`) are not supported +### Configurable Support + +Powered with [**`Roo Rocket`**](https://github.com/NamesMT/roo-rocket), the registry supports configurable items like: + +- `mcp` with access token inputs. +- `mode` / `prompt` with feature flags. +- And further customizations that a creator can imagine. + - E.g: a `package` could prompt you for the location of its context folder. + ## Contributing Process To contribute your package to the official repository, follow these steps: @@ -152,12 +110,12 @@ git clone https://github.com/YOUR-USERNAME/Roo-Code-Marketplace.git cd Roo-Code-Marketplace ``` -### 3. Create Your Package +### 3. Create Your Item -1. Create a new directory for your package with an appropriate name -2. Add the required metadata files and component directories +1. Create a new directory for your item with an appropriate name +2. Add the required metadata files (and subitem directories for `package`) 3. Follow the structure and format described above -4. Add documentation in a README.md file +4. Add `sourceUrl` that points to a repository or post with info/document for the item. Example of creating a simple package: @@ -218,9 +176,11 @@ After submitting your pull request: - **Semantic Versioning**: Follow semantic versioning for version numbers - **Consistent Naming**: Use clear, descriptive names for components -## Example Package +## Example package metadatas -Here's a comprehensive example of a data science package that includes both internal components and references to external components: +### Data Science Toolkit + +Here's an example of a data science package: **data-science-toolkit/metadata.en.yml**: @@ -235,14 +195,6 @@ tags: - analysis - visualization - machine learning -items: - # External components (outside this package directory) - - type: "prompt" - path: "../shared-prompts/data-cleaning" - - type: "mcp" - path: "../../ml-tools/model-trainer" - - type: "mode" - path: "../visualization-tools/chart-creator-mode" ``` **data-science-toolkit/modes/data-scientist-mode/metadata.en.yml**: @@ -258,7 +210,7 @@ tags: - analysis ``` -**shared-prompts/data-cleaning/metadata.en.yml**: +**data-science-toolkit/prompts/data-cleaning/metadata.en.yml**: ```yaml name: "Data Cleaning Prompt" @@ -271,6 +223,4 @@ tags: - preprocessing ``` ---- - **Previous**: [Working with Package Details](./04-working-with-details.md) | **Next**: [Adding Custom Sources](./06-adding-custom-sources.md) diff --git a/cline_docs/marketplace/user-guide/06-adding-custom-sources.md b/cline_docs/marketplace/user-guide/06-adding-custom-sources.md index 9e54084ad7..7baf639631 100644 --- a/cline_docs/marketplace/user-guide/06-adding-custom-sources.md +++ b/cline_docs/marketplace/user-guide/06-adding-custom-sources.md @@ -12,21 +12,27 @@ A Marketplace source repository is a Git repository that contains Marketplace it 2. **Valid Metadata**: Each package must include properly formatted metadata files 3. **Git Repository**: The source must be a Git repository accessible via HTTPS -### Creating a New Repository +### Building your registry repository + +#### Start from a sample registry repository + +Check the branches of the [**rm-samples**](https://github.com/NamesMT/rm-samples) repository here. + +#### Creating a New Repository 1. Create a new repository on GitHub, GitLab, or another Git hosting service 2. Initialize the repository with a README.md file 3. Clone the repository to your local machine: ```bash -git clone https://github.com/your-username/your-package-repo.git -cd your-package-repo +git clone https://github.com/your-username/your-registry-repo.git +cd your-registry-repo ``` -4. Create the basic repository structure: +4. Create the basic registry structure: ```bash -mkdir -p packages modes "mcps" prompts +mkdir -p packages modes mcps prompts touch metadata.en.yml ``` @@ -46,55 +52,6 @@ git commit -m "Initialize package repository structure" git push origin main ``` -## Required Structure and Metadata - -A source repository must follow a specific structure to be properly recognized by the Marketplace: - -### Repository Structure - -``` -repository-root/ -├── metadata.en.yml # Repository metadata -├── README.md # Repository documentation -├── packages/ # Directory for package components -│ ├── package-1/ -│ │ ├── metadata.en.yml # Package metadata -│ │ └── README.md -│ └── package-2/ -│ ├── metadata.en.yml -│ └── README.md -├── modes/ # Directory for mode components -│ └── custom-mode/ -│ └── metadata.en.yml -├── mcps/ # Directory for MCP server components -│ └── custom-server/ -│ └── metadata.en.yml -└── prompts/ # Directory for prompt components - └── custom-prompt/ - └── metadata.en.yml -``` - -### Repository Metadata - -The root `metadata.en.yml` file describes the repository itself: - -```yaml -name: "Custom Roopository" -description: "A collection of specialized components for data science workflows" -version: "1.0.0" -author: "Your Name or Organization" -tags: - - custom - - data-science -``` - -### Item Organization - -- Item should be organized by type in their respective directories -- Each item must have its own directory containing a metadata file -- Items can be nested within packages as subcomponents -- Follow the same structure as described in [Adding Packages](./05-adding-packages.md) - ## Adding Sources to Roo Code Once you have a properly structured source repository, you can add it to your Roo Code Marketplace as a source: @@ -114,15 +71,15 @@ Roo Code comes with a default package source: 4. Click the "Add Source" button 5. Enter the repository URL: - Format: `https://github.com/username/repository.git` - - Example: `https://github.com/your-username/your-package-repo.git` + - Example: `https://github.com/your-username/your-registry-repo.git` 6. Click "Add" to save the source ### Managing Sources -The "Sources" tab provides several options for managing your package sources: +The "Sources" tab provides several options for managing your registry sources: 1. **Remove**: Delete a source from your configuration -2. **Refresh**: Update the item list from a sources - this is forced git clone/pull to override local caching of data +2. **Refresh**: Update the item list from a source - this is forced git clone/pull to override local caching of data ### Source Caching and Refreshing