CmdForge/olddocs/COLLECTIONS.md

# 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

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

```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

For reference, collections can be defined in YAML format:

```yaml
# 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`