diff --git a/olddocs/COLLECTIONS.md b/olddocs/COLLECTIONS.md index cb907cd..7d88ea1 100644 --- a/olddocs/COLLECTIONS.md +++ b/olddocs/COLLECTIONS.md @@ -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 +``` + +``` +$ 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 " \ + -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` diff --git a/olddocs/REGISTRY.md b/olddocs/REGISTRY.md index 4db403f..44aa97e 100644 --- a/olddocs/REGISTRY.md +++ b/olddocs/REGISTRY.md @@ -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: