Update collections documentation with implementation details
- Mark collections CLI as fully implemented - Add admin management UI documentation - Update CLI command examples (cmdforge collections list/info/install) - Add API endpoint documentation - Include example output and usage instructions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
ae6ec7cea1
commit
205cd8d9cf
|
|
@ -1,13 +1,12 @@
|
||||||
# CmdForge Collections
|
# CmdForge Collections
|
||||||
|
|
||||||
> **Document Status (January 2026)**: Collections are partially implemented:
|
> **Document Status (January 2026)**: Collections are fully implemented:
|
||||||
> - ✅ API endpoints (`/api/v1/collections`, etc.)
|
> - ✅ API endpoints (`/api/v1/collections`, `/api/v1/admin/collections`)
|
||||||
> - ✅ Web UI pages (`/collections`, `/collections/:name`)
|
> - ✅ Web UI pages (`/collections`, `/collections/:name`)
|
||||||
|
> - ✅ Admin management UI (`/dashboard/admin/collections`)
|
||||||
> - ✅ Database schema
|
> - ✅ Database schema
|
||||||
> - ❌ CLI commands (`cmdforge collections list/install`) - Not implemented
|
> - ✅ CLI commands (`cmdforge collections list/info/install`)
|
||||||
> - ❌ Registry repo sync - Not implemented
|
> - ❌ Registry repo sync - Not implemented (collections managed via admin UI)
|
||||||
>
|
|
||||||
> Collections can be browsed on the web and via API, but must be installed tool-by-tool via CLI.
|
|
||||||
|
|
||||||
Collections are curated groups of tools that can be installed together with a single command.
|
Collections are curated groups of tools that can be installed together with a single command.
|
||||||
|
|
||||||
|
|
@ -18,9 +17,171 @@ Collections are curated groups of tools that can be installed together with a si
|
||||||
3. **Source bundles**: "fabric-text" with all Fabric text processing patterns
|
3. **Source bundles**: "fabric-text" with all Fabric text processing patterns
|
||||||
4. **Workflow packages**: Tools that work well together for a specific task
|
4. **Workflow packages**: Tools that work well together for a specific task
|
||||||
|
|
||||||
|
## CLI Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List available collections
|
||||||
|
cmdforge collections list
|
||||||
|
|
||||||
|
# List in JSON format
|
||||||
|
cmdforge collections list --json
|
||||||
|
|
||||||
|
# View collection details
|
||||||
|
cmdforge collections info writing-toolkit
|
||||||
|
|
||||||
|
# View details in JSON format
|
||||||
|
cmdforge collections info writing-toolkit --json
|
||||||
|
|
||||||
|
# Install all tools in a collection
|
||||||
|
cmdforge collections install writing-toolkit
|
||||||
|
|
||||||
|
# Install with pinned versions from collection
|
||||||
|
cmdforge collections install writing-toolkit --pinned
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example Output
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cmdforge collections list
|
||||||
|
Available collections (1):
|
||||||
|
|
||||||
|
development-hub
|
||||||
|
Development-Hub
|
||||||
|
Collection of tools for the development-hub application.
|
||||||
|
Tools: 2
|
||||||
|
|
||||||
|
Install a collection with: cmdforge collections install <name>
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cmdforge collections info development-hub
|
||||||
|
Development-Hub
|
||||||
|
==================================================
|
||||||
|
|
||||||
|
Collection of tools for the development-hub application.
|
||||||
|
|
||||||
|
Maintainer: official
|
||||||
|
Tags: Development, Coding, Programming
|
||||||
|
|
||||||
|
Tools (2):
|
||||||
|
- rob/audit-goals
|
||||||
|
- rob/realign-goals
|
||||||
|
|
||||||
|
Install all: cmdforge collections install development-hub
|
||||||
|
```
|
||||||
|
|
||||||
|
## Admin Management
|
||||||
|
|
||||||
|
Collections are managed via the admin dashboard at `/dashboard/admin/collections`.
|
||||||
|
|
||||||
|
### Admin UI Features
|
||||||
|
|
||||||
|
- **List collections**: View all collections with tool counts and tags
|
||||||
|
- **Create collection**: Add new collection with name, display name, description, tools
|
||||||
|
- **Edit collection**: Update existing collection details and tool list
|
||||||
|
- **Delete collection**: Remove a collection (does not uninstall tools)
|
||||||
|
|
||||||
|
### Admin API Endpoints
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/v1/admin/collections # List all collections (admin)
|
||||||
|
POST /api/v1/admin/collections # Create collection (admin)
|
||||||
|
PUT /api/v1/admin/collections/:name # Update collection (admin)
|
||||||
|
DELETE /api/v1/admin/collections/:name # Delete collection (admin)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creating a Collection via API
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST https://cmdforge.brrd.tech/api/v1/admin/collections \
|
||||||
|
-H "Authorization: Bearer <admin-token>" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"name": "writing-toolkit",
|
||||||
|
"display_name": "Writing Toolkit",
|
||||||
|
"description": "Essential tools for writers",
|
||||||
|
"maintainer": "official",
|
||||||
|
"tools": ["official/fix-grammar", "official/simplify"],
|
||||||
|
"pinned": {"official/fix-grammar": "1.0.0"},
|
||||||
|
"tags": ["writing", "editing"]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Public API Endpoints
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/v1/collections # List all collections (summary)
|
||||||
|
GET /api/v1/collections/:name # Get collection details with tool info
|
||||||
|
```
|
||||||
|
|
||||||
|
### List Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"name": "writing-toolkit",
|
||||||
|
"display_name": "Writing Toolkit",
|
||||||
|
"description": "Essential tools for writers",
|
||||||
|
"maintainer": "official",
|
||||||
|
"icon": "pencil",
|
||||||
|
"tags": ["writing", "editing"],
|
||||||
|
"tool_count": 5
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Detail Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"name": "writing-toolkit",
|
||||||
|
"display_name": "Writing Toolkit",
|
||||||
|
"description": "Essential tools for writers",
|
||||||
|
"maintainer": "official",
|
||||||
|
"icon": "pencil",
|
||||||
|
"tags": ["writing", "editing"],
|
||||||
|
"tools": [
|
||||||
|
{
|
||||||
|
"owner": "official",
|
||||||
|
"name": "fix-grammar",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Fix grammar issues in text",
|
||||||
|
"category": "Writing",
|
||||||
|
"downloads": 150,
|
||||||
|
"pinned_version": "1.0.0"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE collections (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
name TEXT UNIQUE NOT NULL,
|
||||||
|
display_name TEXT NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
icon TEXT,
|
||||||
|
maintainer TEXT NOT NULL,
|
||||||
|
tools TEXT NOT NULL, -- JSON array of tool refs (e.g., ["owner/name"])
|
||||||
|
pinned TEXT, -- JSON object of version constraints
|
||||||
|
tags TEXT, -- JSON array
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_collections_name ON collections(name);
|
||||||
|
CREATE INDEX idx_collections_maintainer ON collections(maintainer);
|
||||||
|
```
|
||||||
|
|
||||||
## Collection Manifest Format
|
## Collection Manifest Format
|
||||||
|
|
||||||
Collections are defined in the registry repo under `collections/`:
|
For reference, collections can be defined in YAML format:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# collections/writing-toolkit.yaml
|
# collections/writing-toolkit.yaml
|
||||||
|
|
@ -39,15 +200,7 @@ tools:
|
||||||
|
|
||||||
# Optional: version constraints
|
# Optional: version constraints
|
||||||
pinned:
|
pinned:
|
||||||
official/fix-grammar: "^1.0.0"
|
official/fix-grammar: "1.0.0"
|
||||||
|
|
||||||
# Optional: suggested order for documentation
|
|
||||||
order:
|
|
||||||
- official/fix-grammar
|
|
||||||
- official/proofread
|
|
||||||
- official/simplify
|
|
||||||
- official/tone-shift
|
|
||||||
- official/expand
|
|
||||||
|
|
||||||
tags:
|
tags:
|
||||||
- writing
|
- writing
|
||||||
|
|
@ -55,51 +208,6 @@ tags:
|
||||||
- grammar
|
- grammar
|
||||||
```
|
```
|
||||||
|
|
||||||
## CLI Usage
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# List available collections
|
|
||||||
cmdforge collections list
|
|
||||||
|
|
||||||
# View collection details
|
|
||||||
cmdforge collections info writing-toolkit
|
|
||||||
|
|
||||||
# Install all tools in a collection
|
|
||||||
cmdforge collections install writing-toolkit
|
|
||||||
|
|
||||||
# Install with version constraints from collection
|
|
||||||
cmdforge collections install writing-toolkit --pinned
|
|
||||||
```
|
|
||||||
|
|
||||||
## API Endpoints
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /api/v1/collections # List all collections
|
|
||||||
GET /api/v1/collections/:name # Get collection details with tool info
|
|
||||||
GET /api/v1/collections/:name/tools # Get just the tools list
|
|
||||||
```
|
|
||||||
|
|
||||||
## Database Schema
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE collections (
|
|
||||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
||||||
name TEXT UNIQUE NOT NULL,
|
|
||||||
display_name TEXT NOT NULL,
|
|
||||||
description TEXT,
|
|
||||||
icon TEXT,
|
|
||||||
maintainer TEXT NOT NULL,
|
|
||||||
tools TEXT NOT NULL, -- JSON array of tool refs
|
|
||||||
pinned TEXT, -- JSON object of version constraints
|
|
||||||
tags TEXT, -- JSON array
|
|
||||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
||||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
||||||
);
|
|
||||||
|
|
||||||
CREATE INDEX idx_collections_name ON collections(name);
|
|
||||||
CREATE INDEX idx_collections_maintainer ON collections(maintainer);
|
|
||||||
```
|
|
||||||
|
|
||||||
## Web UI
|
## Web UI
|
||||||
|
|
||||||
- `/collections` - Browse all collections
|
- `/collections` - Browse all collections
|
||||||
|
|
@ -107,19 +215,9 @@ CREATE INDEX idx_collections_maintainer ON collections(maintainer);
|
||||||
- Install button that shows CLI command
|
- Install button that shows CLI command
|
||||||
- Filter by tag, maintainer
|
- Filter by tag, maintainer
|
||||||
|
|
||||||
## Sync from Registry Repo
|
## Implementation Files
|
||||||
|
|
||||||
Collections sync from the registry repo just like tools:
|
- **CLI**: `src/cmdforge/cli/collections_commands.py`
|
||||||
|
- **Registry Client**: `src/cmdforge/registry_client.py` (`get_collections`, `get_collection`)
|
||||||
```
|
- **API**: `src/cmdforge/registry/app.py` (public and admin endpoints)
|
||||||
CmdForge-Registry/
|
- **Admin Templates**: `src/cmdforge/web/templates/admin/collections.html`, `collection_form.html`
|
||||||
├── tools/
|
|
||||||
│ └── ...
|
|
||||||
└── collections/
|
|
||||||
├── writing-toolkit.yaml
|
|
||||||
├── data-science.yaml
|
|
||||||
├── fabric-text.yaml
|
|
||||||
└── fabric-code.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
The webhook sync process reads `collections/*.yaml` and upserts to database.
|
|
||||||
|
|
|
||||||
|
|
@ -353,16 +353,33 @@ Response:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# List available collections
|
# List available collections
|
||||||
cmdforge registry collections
|
cmdforge collections list
|
||||||
|
|
||||||
|
# List in JSON format
|
||||||
|
cmdforge collections list --json
|
||||||
|
|
||||||
# View collection details
|
# View collection details
|
||||||
cmdforge registry collections text-processing-essentials
|
cmdforge collections info text-processing-essentials
|
||||||
|
|
||||||
|
# View in JSON format
|
||||||
|
cmdforge collections info text-processing-essentials --json
|
||||||
|
|
||||||
# Install all tools in a collection
|
# Install all tools in a collection
|
||||||
cmdforge registry install --collection text-processing-essentials
|
cmdforge collections install text-processing-essentials
|
||||||
|
|
||||||
# Show what would be installed (dry run)
|
# Install with pinned versions from collection
|
||||||
cmdforge registry install --collection text-processing-essentials --dry-run
|
cmdforge collections install text-processing-essentials --pinned
|
||||||
|
```
|
||||||
|
|
||||||
|
### Admin Collections API
|
||||||
|
|
||||||
|
Collections are managed via the admin dashboard at `/dashboard/admin/collections`:
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/v1/admin/collections # List all collections (admin)
|
||||||
|
POST /api/v1/admin/collections # Create collection (admin)
|
||||||
|
PUT /api/v1/admin/collections/:name # Update collection (admin)
|
||||||
|
DELETE /api/v1/admin/collections/:name # Delete collection (admin)
|
||||||
```
|
```
|
||||||
|
|
||||||
**Schema compatibility note:** The current CmdForge config parser may reject unknown top-level keys like `deprecated`, `replacement`, and `registry`. Before implementing registry features:
|
**Schema compatibility note:** The current CmdForge config parser may reject unknown top-level keys like `deprecated`, `replacement`, and `registry`. Before implementing registry features:
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue