CmdForge Collections

Collections are curated groups of tools that can be installed together with a single command.

Implementation Status

Feature	Status
Public API endpoints	Done
Admin API endpoints	Done
Web UI browse pages	Done
Admin management UI	Done
Database schema	Done
CLI commands	Done
Registry repo sync	Not implemented

Use Cases

1. Thematic bundles: "writing-toolkit" with grammar, tone, simplify tools
2. Application stacks: "data-science" with json-extract, csv-insights, etc.
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

List Collections

# List available collections
cmdforge collections list

# List in JSON format
cmdforge collections list --json

Example output:

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>

View Collection Details

# View collection details
cmdforge collections info development-hub

# View in JSON format
cmdforge collections info development-hub --json

Example output:

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

Install Collection

# Install all tools in a collection
cmdforge collections install development-hub

# Install with pinned versions from collection
cmdforge collections install development-hub --pinned

Example output:

Installing collection: Development-Hub
Tools to install: 2

  Installing rob/audit-goals... v1.0.0
  Installing rob/realign-goals... v1.0.0

Installed: 2/2

Collection 'development-hub' installed successfully!

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

Method	Endpoint	Description
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

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

Method	Endpoint	Description
GET	/api/v1/collections	List all collections (summary)
GET	/api/v1/collections/:name	Get collection details with tool info

List Response

{
  "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

{
  "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

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);

Collection Manifest Format

For reference, collections can be defined in YAML format:

# collections/writing-toolkit.yaml
name: writing-toolkit
display_name: Writing Toolkit
description: Essential tools for writers and editors
icon: pencil  # Optional icon identifier
maintainer: official  # Publisher who maintains this collection

tools:
  - official/fix-grammar
  - official/simplify
  - official/tone-shift
  - official/expand
  - official/proofread

# Optional: version constraints
pinned:
  official/fix-grammar: "1.0.0"

tags:
  - writing
  - editing
  - grammar

Web UI

• /collections - Browse all collections
• /collections/:name - Collection detail page with tool grid
• Install button that shows CLI command
• Filter by tag, maintainer

Implementation Files

Component	File
CLI commands	src/cmdforge/cli/collections_commands.py
Registry client	src/cmdforge/registry_client.py
API endpoints	src/cmdforge/registry/app.py
Admin templates	src/cmdforge/web/templates/admin/collections.html
Admin form	src/cmdforge/web/templates/admin/collection_form.html