5.9 KiB

Raw Blame History

CmdForge Collections

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/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.

Use Cases

Thematic bundles: "writing-toolkit" with grammar, tone, simplify tools
Application stacks: "data-science" with json-extract, csv-insights, etc.
Source bundles: "fabric-text" with all Fabric text processing patterns
Workflow packages: Tools that work well together for a specific task

CLI Usage

# 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

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

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

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

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

5.9 KiB Raw Blame History