feat(marketplace): command consolidation + 8 new plugins (v8.1.0 → v9.0.0) [BREAKING]

Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 14:52:11 -05:00
parent 5098422858
commit 2d51df7a42
321 changed files with 13582 additions and 1019 deletions
--- a/plugins/saas-api-platform/commands/api-docs.md
+++ b/plugins/saas-api-platform/commands/api-docs.md
@@ -0,0 +1,109 @@
+---
+name: api docs
+description: Generate or update OpenAPI specification from code
+agent: api-architect
+---
+
+# /api docs - OpenAPI Specification Generator
+
+## Skills to Load
+
+- skills/openapi-conventions.md
+- skills/framework-detection.md
+- skills/visual-header.md
+
+## Visual Output
+
+Display header: `API-PLATFORM - Docs`
+
+## Usage
+
+```
+/api docs [--format=yaml|json] [--output=<path>] [--update]
+```
+
+**Arguments:**
+- `--format`: Output format, default `yaml`
+- `--output`: Output file path (default: `openapi.yaml` or `openapi.json` in project root)
+- `--update`: Update existing spec instead of regenerating from scratch
+
+## Process
+
+### 1. Scan Route Definitions
+
+Read all route files identified during `/api setup`:
+
+**FastAPI:**
+- Parse `@app.get`, `@app.post`, `@router.get`, etc. decorators
+- Extract path, method, response_model, status_code, dependencies
+- Read Pydantic model definitions for schema extraction
+- Capture docstrings as endpoint descriptions
+
+**Express:**
+- Parse `router.get`, `router.post`, etc. calls
+- Extract path patterns and middleware chains
+- Read Zod/Joi/JSON Schema validators for schema extraction
+- Capture JSDoc comments as endpoint descriptions
+
+### 2. Build OpenAPI Document
+
+Generate OpenAPI 3.x specification:
+
+- **Info section**: Title from package name, version from package config
+- **Servers**: Extract from environment or configuration
+- **Paths**: One entry per endpoint with method, parameters, request body, responses
+- **Components/Schemas**: Extracted from model/schema definitions
+- **Security schemes**: Based on detected auth patterns (JWT, API key, OAuth2)
+- **Tags**: Group endpoints by resource/router prefix
+
+### 3. Handle Updates (--update mode)
+
+When updating existing spec:
+- Preserve manually-added descriptions, examples, and extensions
+- Add new endpoints not yet in spec
+- Flag removed endpoints for user review (do not auto-delete)
+- Update schemas that changed in code
+- Show diff of changes before writing
+
+### 4. Write Output
+
+Write the generated or updated spec to the target file.
+
+## Output Format
+
+```
+----------------------------------------------------------------------+
+|  API-PLATFORM - Docs                                                 |
+----------------------------------------------------------------------+
+
+Mode: Generate (new)
+Format: YAML
+Output: ./openapi.yaml
+
+Extracted:
+  Routes:     14 endpoints from 4 files
+  Schemas:    8 models extracted
+  Auth:       JWT Bearer scheme detected
+  Tags:       users, orders, products, auth
+
+OpenAPI 3.0.3 spec written to openapi.yaml
+
+Sections Generated:
+  [+] info          (title, version, description)
+  [+] servers       (1 server)
+  [+] paths         (14 operations)
+  [+] components    (8 schemas, 1 security scheme)
+  [+] tags          (4 tags)
+
+Next Steps:
+  - Review generated spec for accuracy
+  - Add examples to request/response bodies
+  - Run /api validate to verify consistency
+```
+
+## Important Notes
+
+- Generated spec is a starting point; review and enrich with examples
+- Descriptions are extracted from docstrings when available
+- Complex schemas (inheritance, unions) may need manual adjustment
+- The `--update` flag preserves manual additions to the spec
--- a/plugins/saas-api-platform/commands/api-middleware.md
+++ b/plugins/saas-api-platform/commands/api-middleware.md
@@ -0,0 +1,132 @@
+---
+name: api middleware
+description: Add and configure API middleware
+agent: api-architect
+---
+
+# /api middleware - Middleware Manager
+
+## Skills to Load
+
+- skills/middleware-catalog.md
+- skills/framework-detection.md
+- skills/visual-header.md
+
+## Visual Output
+
+Display header: `API-PLATFORM - Middleware`
+
+## Usage
+
+```
+/api middleware <action> [<type>] [--options]
+```
+
+**Actions:**
+- `add <type>` - Add middleware to the application
+- `list` - List currently configured middleware
+- `remove <type>` - Remove middleware configuration
+
+**Middleware Types:**
+- `auth` - Authentication (JWT, OAuth2, API key)
+- `cors` - Cross-Origin Resource Sharing
+- `rate-limit` - Rate limiting per client/IP
+- `logging` - Request/response logging
+- `error-handler` - Global error handling and formatting
+- `validation` - Request body/query validation
+
+## Process
+
+### 1. Detect Framework
+
+Read `.api-platform.json` to determine target framework. Middleware implementation differs significantly between FastAPI and Express.
+
+### 2. Add Middleware (`add` action)
+
+**Auth Middleware:**
+- Ask user for auth type: JWT Bearer, OAuth2, API key header
+- Generate middleware file with token validation logic
+- Add dependency/middleware registration to app
+- Create auth utility functions (decode token, verify permissions)
+- Generate `.env.example` entries for secrets (JWT_SECRET, etc.)
+
+**CORS Middleware:**
+- Ask for allowed origins (default: `["*"]` for development)
+- Configure allowed methods, headers, credentials
+- Set max_age for preflight caching
+- FastAPI: `CORSMiddleware` configuration
+- Express: `cors` package configuration
+
+**Rate Limiting:**
+- Ask for rate limit strategy: fixed window, sliding window, token bucket
+- Configure limits per endpoint or global (requests/minute)
+- Set burst allowance
+- Configure response headers (X-RateLimit-Limit, X-RateLimit-Remaining)
+- FastAPI: `slowapi` or custom middleware
+- Express: `express-rate-limit` package
+
+**Logging:**
+- Configure log format (JSON structured, Apache combined, custom)
+- Set log levels per environment (debug for dev, info for prod)
+- Include request ID generation and propagation
+- Configure sensitive field masking (Authorization header, passwords)
+- FastAPI: custom middleware with `structlog` or `logging`
+- Express: `morgan` or `pino-http`
+
+**Error Handler:**
+- Global exception/error handler with consistent response format
+- Map framework exceptions to HTTP status codes
+- Include request ID in error responses
+- Mask internal details in production mode
+- Log full stack traces server-side
+
+**Validation:**
+- Request body validation using framework-native tools
+- Query parameter validation and type coercion
+- Custom validation error response format
+
+### 3. List Middleware (`list` action)
+
+Scan app configuration and display active middleware in execution order.
+
+### 4. Remove Middleware (`remove` action)
+
+Remove middleware registration and associated files. Warn about dependencies.
+
+## Output Format
+
+```
+----------------------------------------------------------------------+
+|  API-PLATFORM - Middleware                                            |
+----------------------------------------------------------------------+
+
+Action: add
+Type: rate-limit
+Framework: FastAPI
+
+Files Created/Modified:
+  [+] app/middleware/rate_limit.py    (rate limiter implementation)
+  [~] app/main.py                    (middleware registered)
+  [~] .env.example                   (RATE_LIMIT_PER_MINUTE added)
+
+Configuration:
+  Strategy:     Sliding window
+  Global Limit: 60 requests/minute
+  Burst:        10 additional
+  Headers:      X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
+
+Dependencies Added:
+  slowapi>=0.1.9
+
+Next Steps:
+  - pip install slowapi
+  - Configure RATE_LIMIT_PER_MINUTE in .env
+  - Override per-endpoint limits in route decorators if needed
+```
+
+## Important Notes
+
+- Middleware order matters; auth should run before rate-limiting
+- CORS must be configured before route handlers
+- Error handler should be the outermost middleware
+- Rate limiting should use persistent store (Redis) in production
--- a/plugins/saas-api-platform/commands/api-scaffold.md
+++ b/plugins/saas-api-platform/commands/api-scaffold.md
@@ -0,0 +1,123 @@
+---
+name: api scaffold
+description: Generate API routes, models, and schemas
+agent: api-architect
+---
+
+# /api scaffold - Route and Model Scaffolding
+
+## Skills to Load
+
+- skills/framework-detection.md
+- skills/route-patterns.md
+- skills/openapi-conventions.md
+- skills/visual-header.md
+
+## Visual Output
+
+Display header: `API-PLATFORM - Scaffold`
+
+## Usage
+
+```
+/api scaffold <resource-name> [--methods=GET,POST,PUT,DELETE] [--nested-under=<parent>]
+```
+
+**Arguments:**
+- `<resource-name>`: Name of the resource (e.g., `users`, `orders`, `products`)
+- `--methods`: Comma-separated HTTP methods (default: all CRUD)
+- `--nested-under`: Create as nested resource under parent (e.g., `--nested-under=users`)
+
+## Prerequisites
+
+Run `/api setup` first. This command reads `.api-platform.json` for framework and conventions.
+
+## Process
+
+### 1. Read Configuration
+
+Load `.api-platform.json` to determine:
+- Target framework (FastAPI or Express)
+- Route and model directories
+- Versioning scheme
+- Response format conventions
+
+### 2. Generate Route File
+
+Create route/controller file with endpoints:
+
+**FastAPI Example (`routes/{resource}.py`):**
+- `GET /{version}/{resource}` - List with pagination, filtering, sorting
+- `GET /{version}/{resource}/{id}` - Get by ID with 404 handling
+- `POST /{version}/{resource}` - Create with request body validation
+- `PUT /{version}/{resource}/{id}` - Full update with 404 handling
+- `PATCH /{version}/{resource}/{id}` - Partial update
+- `DELETE /{version}/{resource}/{id}` - Delete with 204 response
+
+**Express Example (`routes/{resource}.js`):**
+- Same endpoints adapted to Express router patterns
+- Includes error handling middleware chain
+
+### 3. Generate Request/Response Models
+
+Create schema definitions appropriate to the framework:
+
+- **FastAPI**: Pydantic models in `models/{resource}.py`
+  - `{Resource}Create` - POST/PUT request body
+  - `{Resource}Update` - PATCH request body (all fields optional)
+  - `{Resource}Response` - Response model with `id`, timestamps
+  - `{Resource}List` - Paginated list wrapper
+
+- **Express**: JSON Schema or Zod schemas in `schemas/{resource}.js`
+  - Create schema, Update schema, Response schema
+
+### 4. Generate Validation Schemas
+
+Add input validation:
+- Required fields, type constraints, string length limits
+- Enum values where appropriate
+- Nested object validation for complex resources
+
+### 5. Register Routes
+
+Update the main router/app file to include new routes:
+- Add import statement
+- Register route prefix
+- Maintain alphabetical ordering of imports
+
+## Output Format
+
+```
+----------------------------------------------------------------------+
+|  API-PLATFORM - Scaffold                                             |
+----------------------------------------------------------------------+
+
+Resource: orders
+Framework: FastAPI
+Versioning: /v1/
+
+Files Created:
+  [+] app/routes/orders.py      (6 endpoints)
+  [+] app/models/orders.py      (4 Pydantic models)
+  [~] app/main.py               (route registered)
+
+Endpoints Generated:
+  GET    /v1/orders              List with pagination
+  GET    /v1/orders/{id}         Get by ID
+  POST   /v1/orders              Create
+  PUT    /v1/orders/{id}         Full update
+  PATCH  /v1/orders/{id}         Partial update
+  DELETE /v1/orders/{id}         Delete
+
+Next Steps:
+  - Add business logic to route handlers
+  - Run /api validate to check against OpenAPI spec
+  - Run /api test-routes to generate test cases
+```
+
+## Nested Resources
+
+When `--nested-under` is specified:
+- Routes are prefixed: `/{parent}/{parent_id}/{resource}`
+- Models include `{parent}_id` foreign key field
+- Route file includes parent ID path parameter validation
--- a/plugins/saas-api-platform/commands/api-setup.md
+++ b/plugins/saas-api-platform/commands/api-setup.md
@@ -0,0 +1,99 @@
+---
+name: api setup
+description: Setup wizard for saas-api-platform
+agent: api-architect
+---
+
+# /api setup - API Platform Setup Wizard
+
+## Skills to Load
+
+- skills/framework-detection.md
+- skills/visual-header.md
+
+## Visual Output
+
+Display header: `API-PLATFORM - Setup Wizard`
+
+## Usage
+
+```
+/api setup
+```
+
+## Workflow
+
+### Phase 1: Framework Detection
+
+Scan the project root for framework indicators:
+
+| File / Pattern | Framework | Confidence |
+|----------------|-----------|------------|
+| `main.py` with `from fastapi` | FastAPI | High |
+| `app.py` with `from fastapi` | FastAPI | High |
+| `requirements.txt` containing `fastapi` | FastAPI | Medium |
+| `pyproject.toml` with `fastapi` dependency | FastAPI | Medium |
+| `package.json` with `express` dependency | Express | High |
+| `app.js` or `app.ts` with `require('express')` | Express | High |
+| `tsconfig.json` + express in deps | Express (TypeScript) | High |
+
+If no framework detected, ask user to select one.
+
+### Phase 2: Project Structure Mapping
+
+Identify existing project layout:
+
+- **Route files**: Locate route/controller directories
+- **Models**: Locate model/schema definition files
+- **Middleware**: Locate existing middleware
+- **Tests**: Locate test directories and test runner config
+- **OpenAPI spec**: Check for existing `openapi.yaml`, `openapi.json`, or `swagger.json`
+
+Report findings to user with directory tree.
+
+### Phase 3: Convention Configuration
+
+Ask user about project conventions:
+
+- **Route style**: RESTful nested (`/users/{id}/posts`) vs flat (`/user-posts`)
+- **Versioning**: URL prefix (`/v1/`) vs header-based vs none
+- **Auth pattern**: JWT, OAuth2, API key, or none
+- **Response format**: JSON:API, HAL, plain JSON
+
+Store decisions in `.api-platform.json` in project root for future commands.
+
+### Phase 4: Validation
+
+Verify detected configuration:
+
+- Confirm framework version
+- Confirm route directory location
+- Confirm model directory location
+- Display summary with all detected settings
+
+## Output Format
+
+```
+----------------------------------------------------------------------+
+|  API-PLATFORM - Setup Wizard                                         |
+----------------------------------------------------------------------+
+
+Framework:     FastAPI 0.104.1
+Route Dir:     ./app/routes/
+Models Dir:    ./app/models/
+Tests Dir:     ./tests/
+OpenAPI Spec:  ./openapi.yaml (existing)
+
+Conventions:
+  Versioning:  /v1/ URL prefix
+  Auth:        JWT Bearer
+  Response:    Plain JSON
+
+Configuration saved to .api-platform.json
+```
+
+## Important Notes
+
+- This command does NOT create project files; it only detects and configures
+- If `.api-platform.json` already exists, offer to update or keep existing
+- All subsequent commands rely on setup configuration
--- a/plugins/saas-api-platform/commands/api-test-routes.md
+++ b/plugins/saas-api-platform/commands/api-test-routes.md
@@ -0,0 +1,126 @@
+---
+name: api test-routes
+description: Generate request/response test cases for API endpoints
+agent: api-architect
+---
+
+# /api test-routes - API Test Generator
+
+## Skills to Load
+
+- skills/route-patterns.md
+- skills/visual-header.md
+
+## Visual Output
+
+Display header: `API-PLATFORM - Test Routes`
+
+## Usage
+
+```
+/api test-routes [<resource>] [--coverage=basic|full] [--runner=pytest|jest|vitest]
+```
+
+**Arguments:**
+- `<resource>`: Specific resource to generate tests for (default: all)
+- `--coverage`: `basic` generates happy-path only; `full` includes edge cases (default: `full`)
+- `--runner`: Test runner to target (auto-detected from project)
+
+## Prerequisites
+
+Run `/api setup` first. Route files must exist (either manually written or via `/api scaffold`).
+
+## Process
+
+### 1. Detect Test Runner
+
+Auto-detect based on framework:
+- **FastAPI**: `pytest` with `httpx` (TestClient)
+- **Express**: `jest` or `vitest` with `supertest`
+
+Check for existing test config (`pytest.ini`, `jest.config.*`, `vitest.config.*`).
+
+### 2. Scan Endpoints
+
+For each route file, extract:
+- HTTP method and path
+- Required and optional parameters
+- Request body schema with field types and constraints
+- Expected response status codes
+- Authentication requirements
+
+### 3. Generate Test Cases
+
+For each endpoint, generate test cases in categories:
+
+**Happy Path (basic coverage):**
+- Valid request returns expected status code
+- Response body matches expected schema
+- List endpoints return paginated results
+- Create endpoint returns created resource with ID
+
+**Validation (full coverage):**
+- Missing required fields returns 422/400
+- Invalid field types return 422/400
+- String fields exceeding max length return 422/400
+- Invalid enum values return 422/400
+
+**Authentication (full coverage):**
+- Request without auth token returns 401
+- Request with expired token returns 401
+- Request with insufficient permissions returns 403
+
+**Edge Cases (full coverage):**
+- GET non-existent resource returns 404
+- DELETE already-deleted resource returns 404
+- PUT with partial body returns 422/400
+- Concurrent creation of duplicate resources
+
+**Pagination (full coverage for list endpoints):**
+- Default pagination returns correct page size
+- Custom page size works correctly
+- Out-of-range page returns empty results
+- Sort parameters produce correct ordering
+
+### 4. Write Test Files
+
+Create test files in the project test directory:
+- One test file per resource
+- Test fixtures for common setup (auth tokens, sample data)
+- Helper functions for repetitive assertions
+
+## Output Format
+
+```
+----------------------------------------------------------------------+
+|  API-PLATFORM - Test Routes                                          |
+----------------------------------------------------------------------+
+
+Coverage: full
+Runner: pytest + httpx
+Resource: orders
+
+Files Created:
+  [+] tests/test_orders.py      (18 test cases)
+  [+] tests/conftest.py         (fixtures updated)
+
+Test Cases Generated:
+  Happy Path:    6 tests
+  Validation:    5 tests
+  Auth:          3 tests
+  Edge Cases:    4 tests
+
+  Total:         18 test cases for 6 endpoints
+
+Next Steps:
+  - Review generated tests and adjust sample data
+  - Add database fixtures for integration tests
+  - Run: pytest tests/test_orders.py -v
+```
+
+## Important Notes
+
+- Generated tests use placeholder sample data; review and adjust for your domain
+- Auth tests require a fixture that provides valid/invalid tokens
+- Integration tests may need database setup/teardown fixtures
+- Tests follow Arrange-Act-Assert pattern
--- a/plugins/saas-api-platform/commands/api-validate.md
+++ b/plugins/saas-api-platform/commands/api-validate.md
@@ -0,0 +1,124 @@
+---
+name: api validate
+description: Validate routes against OpenAPI specification
+agent: api-validator
+---
+
+# /api validate - OpenAPI Validation
+
+## Skills to Load
+
+- skills/openapi-conventions.md
+- skills/route-patterns.md
+- skills/visual-header.md
+
+## Visual Output
+
+Display header: `API-PLATFORM - Validate`
+
+## Usage
+
+```
+/api validate [--spec=<path>] [--strict]
+```
+
+**Arguments:**
+- `--spec`: Path to OpenAPI spec file (default: auto-detect `openapi.yaml` or `openapi.json`)
+- `--strict`: Treat warnings as errors
+
+## Prerequisites
+
+Run `/api setup` first. Requires an existing OpenAPI specification to validate against.
+
+## Process
+
+### 1. Locate OpenAPI Spec
+
+Search for spec file in order:
+1. Path provided via `--spec` flag
+2. `openapi.yaml` in project root
+3. `openapi.json` in project root
+4. `swagger.yaml` or `swagger.json` in project root
+5. `docs/openapi.yaml` or `docs/openapi.json`
+
+If not found, report error and suggest `/api docs` to generate one.
+
+### 2. Parse Route Definitions
+
+Scan route files to extract implemented endpoints:
+- HTTP method and path pattern
+- Path parameters and query parameters
+- Request body schema (if POST/PUT/PATCH)
+- Response status codes and schemas
+- Authentication requirements
+
+### 3. Compare Against Spec
+
+Run validation checks:
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Missing endpoint in spec | FAIL | Route exists in code but not in OpenAPI spec |
+| Missing endpoint in code | FAIL | Spec defines endpoint not implemented |
+| Parameter mismatch | FAIL | Path/query parameters differ between code and spec |
+| Schema mismatch | WARN | Request/response model fields differ from spec |
+| Missing response codes | WARN | Code returns status codes not documented in spec |
+| Missing descriptions | INFO | Endpoints or parameters lack descriptions |
+| Missing examples | INFO | Spec lacks request/response examples |
+| Deprecated endpoint still active | WARN | Spec marks endpoint deprecated but code still serves it |
+
+### 4. Generate Report
+
+Group findings by severity and provide actionable fixes.
+
+## Output Format
+
+```
+----------------------------------------------------------------------+
+|  API-PLATFORM - Validate                                             |
+----------------------------------------------------------------------+
+
+Spec: openapi.yaml (OpenAPI 3.0.3)
+Routes Scanned: 14 endpoints in 4 files
+Spec Endpoints: 16 defined
+
+FINDINGS
+
+FAIL (2)
+  1. [POST /v1/orders] Missing from OpenAPI spec
+     Fix: Add path definition to openapi.yaml
+
+  2. [GET /v1/users] Query param 'role' not in spec
+     Fix: Add 'role' query parameter to path definition
+
+WARN (3)
+  1. [PUT /v1/products/{id}] Response 422 not documented
+     Fix: Add 422 response to spec with validation error schema
+
+  2. [GET /v1/orders] Schema mismatch - 'total_amount' field
+     Code: float, Spec: string
+     Fix: Update spec to use number type
+
+  3. [DELETE /v1/users/{id}] Marked deprecated in spec
+     Suggestion: Remove endpoint or update spec status
+
+INFO (1)
+  1. [GET /v1/products] Missing response example
+     Suggestion: Add example to improve documentation
+
+SUMMARY
+  Endpoints:  14 implemented / 16 in spec
+  Coverage:   87.5%
+  FAIL:       2 (must fix)
+  WARN:       3 (should fix)
+  INFO:       1 (improve)
+
+VERDICT: FAIL (2 blocking issues)
+```
+
+## Exit Guidance
+
+- FAIL findings: Block deployment, spec and code must agree
+- WARN findings: Fix before release for accurate documentation
+- INFO findings: Improve for developer experience
+- `--strict` mode: All WARN become FAIL
--- a/plugins/saas-api-platform/commands/api.md
+++ b/plugins/saas-api-platform/commands/api.md
@@ -0,0 +1,19 @@
+---
+name: api
+description: API development toolkit — route scaffolding, OpenAPI validation, middleware management
+---
+
+# /api
+
+REST and GraphQL API scaffolding, validation, and documentation for FastAPI and Express.
+
+## Sub-commands
+
+| Sub-command | Description |
+|-------------|-------------|
+| `/api setup` | Setup wizard for saas-api-platform |
+| `/api scaffold` | Generate routes, models, and schemas |
+| `/api validate` | Validate routes against OpenAPI spec |
+| `/api docs` | Generate or update OpenAPI specification |
+| `/api test-routes` | Generate test cases for API endpoints |
+| `/api middleware` | Add and configure middleware |