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
|
||||
|
||||
> **Document Status (January 2026)**: Collections are partially implemented:
|
||||
> - ✅ API endpoints (`/api/v1/collections`, etc.)
|
||||
> **Document Status (January 2026)**: Collections are fully implemented:
|
||||
> - ✅ API endpoints (`/api/v1/collections`, `/api/v1/admin/collections`)
|
||||
> - ✅ Web UI pages (`/collections`, `/collections/:name`)
|
||||
> - ✅ Admin management UI (`/dashboard/admin/collections`)
|
||||
> - ✅ Database schema
|
||||
> - ❌ CLI commands (`cmdforge collections list/install`) - Not implemented
|
||||
> - ❌ Registry repo sync - Not implemented
|
||||
>
|
||||
> Collections can be browsed on the web and via API, but must be installed tool-by-tool via CLI.
|
||||
> - ✅ CLI commands (`cmdforge collections list/info/install`)
|
||||
> - ❌ Registry repo sync - Not implemented (collections managed via admin UI)
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
Collections are defined in the registry repo under `collections/`:
|
||||
For reference, collections can be defined in YAML format:
|
||||
|
||||
```yaml
|
||||
# collections/writing-toolkit.yaml
|
||||
|
|
@ -39,15 +200,7 @@ tools:
|
|||
|
||||
# Optional: version constraints
|
||||
pinned:
|
||||
official/fix-grammar: "^1.0.0"
|
||||
|
||||
# Optional: suggested order for documentation
|
||||
order:
|
||||
- official/fix-grammar
|
||||
- official/proofread
|
||||
- official/simplify
|
||||
- official/tone-shift
|
||||
- official/expand
|
||||
official/fix-grammar: "1.0.0"
|
||||
|
||||
tags:
|
||||
- writing
|
||||
|
|
@ -55,51 +208,6 @@ tags:
|
|||
- 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
|
||||
|
||||
- `/collections` - Browse all collections
|
||||
|
|
@ -107,19 +215,9 @@ CREATE INDEX idx_collections_maintainer ON collections(maintainer);
|
|||
- Install button that shows CLI command
|
||||
- Filter by tag, maintainer
|
||||
|
||||
## Sync from Registry Repo
|
||||
## Implementation Files
|
||||
|
||||
Collections sync from the registry repo just like tools:
|
||||
|
||||
```
|
||||
CmdForge-Registry/
|
||||
├── 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.
|
||||
- **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)
|
||||
- **Admin Templates**: `src/cmdforge/web/templates/admin/collections.html`, `collection_form.html`
|
||||
|
|
|
|||
|
|
@ -353,16 +353,33 @@ Response:
|
|||
|
||||
```bash
|
||||
# List available collections
|
||||
cmdforge registry collections
|
||||
cmdforge collections list
|
||||
|
||||
# List in JSON format
|
||||
cmdforge collections list --json
|
||||
|
||||
# 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
|
||||
cmdforge registry install --collection text-processing-essentials
|
||||
cmdforge collections install text-processing-essentials
|
||||
|
||||
# Show what would be installed (dry run)
|
||||
cmdforge registry install --collection text-processing-essentials --dry-run
|
||||
# Install with pinned versions from collection
|
||||
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue