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>
This commit is contained in:
81
plugins/saas-api-platform/skills/framework-detection.md
Normal file
81
plugins/saas-api-platform/skills/framework-detection.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: framework-detection
|
||||
description: Detect FastAPI vs Express, identify project structure, locate route files and models
|
||||
---
|
||||
|
||||
# Framework Detection
|
||||
|
||||
## Purpose
|
||||
|
||||
Identify the API framework in use and map the project structure. This skill is loaded by the `api-architect` agent during setup and code generation to ensure framework-appropriate output.
|
||||
|
||||
---
|
||||
|
||||
## Detection Rules
|
||||
|
||||
### FastAPI Detection
|
||||
|
||||
| Indicator | Location | Confidence |
|
||||
|-----------|----------|------------|
|
||||
| `from fastapi import` in Python files | `*.py` | High |
|
||||
| `fastapi` in `requirements.txt` | Project root | Medium |
|
||||
| `fastapi` in `pyproject.toml` dependencies | Project root | Medium |
|
||||
| `uvicorn` in requirements alongside fastapi | Project root | High |
|
||||
| `@app.get`, `@router.post` decorators | `*.py` | High |
|
||||
|
||||
**FastAPI Project Structure (typical):**
|
||||
```
|
||||
app/
|
||||
__init__.py
|
||||
main.py # FastAPI app instance, middleware, router includes
|
||||
routes/ # Route modules (one per resource)
|
||||
models/ # Pydantic models (request/response schemas)
|
||||
dependencies/ # Dependency injection functions
|
||||
middleware/ # Custom middleware
|
||||
core/ # Config, security, database setup
|
||||
```
|
||||
|
||||
### Express Detection
|
||||
|
||||
| Indicator | Location | Confidence |
|
||||
|-----------|----------|------------|
|
||||
| `express` in `package.json` dependencies | Project root | High |
|
||||
| `require('express')` or `import express` | `*.js`, `*.ts` | High |
|
||||
| `express.Router()` usage | `*.js`, `*.ts` | High |
|
||||
| `tsconfig.json` present alongside Express | Project root | Express+TS variant |
|
||||
|
||||
**Express Project Structure (typical):**
|
||||
```
|
||||
src/
|
||||
app.js or app.ts # Express app instance, middleware, router mounts
|
||||
routes/ # Route modules (one per resource)
|
||||
models/ # Database models (Sequelize, Mongoose, etc.)
|
||||
schemas/ # Validation schemas (Zod, Joi)
|
||||
middleware/ # Custom middleware
|
||||
config/ # Environment config, database setup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Mapping Procedure
|
||||
|
||||
1. **Check package files first**: `requirements.txt`, `pyproject.toml`, `package.json`
|
||||
2. **Scan entry points**: `main.py`, `app.py`, `app.js`, `app.ts`, `index.js`, `index.ts`
|
||||
3. **Locate route directory**: Search for `routes/`, `routers/`, `controllers/`, `api/`
|
||||
4. **Locate model directory**: Search for `models/`, `schemas/`, `entities/`
|
||||
5. **Locate test directory**: Search for `tests/`, `test/`, `__tests__/`, `spec/`
|
||||
6. **Check for existing OpenAPI spec**: `openapi.yaml`, `openapi.json`, `swagger.*`
|
||||
|
||||
---
|
||||
|
||||
## Framework Version Detection
|
||||
|
||||
**FastAPI**: Parse version from `requirements.txt` pin or `pyproject.toml` constraint. Important for feature availability (e.g., `lifespan` parameter in 0.93+).
|
||||
|
||||
**Express**: Parse version from `package.json` dependencies. Important for middleware compatibility (Express 4 vs 5).
|
||||
|
||||
---
|
||||
|
||||
## Ambiguous Projects
|
||||
|
||||
If both FastAPI and Express indicators are found (monorepo), ask the user which service to target. Store the selection in `.api-platform.json` with a `service_root` field pointing to the specific service directory.
|
||||
137
plugins/saas-api-platform/skills/middleware-catalog.md
Normal file
137
plugins/saas-api-platform/skills/middleware-catalog.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
name: middleware-catalog
|
||||
description: Common middleware patterns for auth, CORS, rate-limiting, logging, and error handling per framework
|
||||
---
|
||||
|
||||
# Middleware Catalog
|
||||
|
||||
## Purpose
|
||||
|
||||
Reference catalog of middleware patterns for FastAPI and Express. This skill is loaded by the `api-architect` agent when adding or configuring middleware, ensuring correct implementation per framework.
|
||||
|
||||
---
|
||||
|
||||
## Middleware Execution Order
|
||||
|
||||
Middleware should be registered in this order (outermost to innermost):
|
||||
|
||||
1. **Error Handler** - Catches all unhandled exceptions
|
||||
2. **CORS** - Must run before any route processing
|
||||
3. **Request ID** - Generate unique ID for tracing
|
||||
4. **Logging** - Log incoming request details
|
||||
5. **Rate Limiting** - Reject excessive requests early
|
||||
6. **Authentication** - Validate credentials
|
||||
7. **Authorization** - Check permissions (often per-route)
|
||||
8. **Validation** - Validate request body/params (often per-route)
|
||||
9. **Route Handler** - Business logic
|
||||
|
||||
---
|
||||
|
||||
## Authentication Middleware
|
||||
|
||||
### JWT Bearer (FastAPI)
|
||||
- Use `fastapi.security.HTTPBearer` dependency
|
||||
- Decode token with `python-jose` or `PyJWT`
|
||||
- Store decoded claims in request state
|
||||
- Return 401 for missing/invalid/expired tokens
|
||||
- Environment: `JWT_SECRET`, `JWT_ALGORITHM` (default HS256)
|
||||
|
||||
### JWT Bearer (Express)
|
||||
- Use `express-jwt` or custom middleware
|
||||
- Decode token from `Authorization: Bearer <token>` header
|
||||
- Attach decoded user to `req.user`
|
||||
- Return 401 for missing/invalid/expired tokens
|
||||
- Environment: `JWT_SECRET`, `JWT_ALGORITHM`
|
||||
|
||||
### API Key
|
||||
- Read from `X-API-Key` header
|
||||
- Compare against stored keys (database or environment)
|
||||
- Return 401 for missing key, 403 for invalid key
|
||||
|
||||
---
|
||||
|
||||
## CORS Middleware
|
||||
|
||||
### FastAPI
|
||||
```python
|
||||
from fastapi.middleware.cors import CORSMiddleware
|
||||
app.add_middleware(
|
||||
CORSMiddleware,
|
||||
allow_origins=["*"], # Restrict in production
|
||||
allow_credentials=True,
|
||||
allow_methods=["*"],
|
||||
allow_headers=["*"],
|
||||
max_age=600,
|
||||
)
|
||||
```
|
||||
|
||||
### Express
|
||||
```javascript
|
||||
const cors = require('cors');
|
||||
app.use(cors({
|
||||
origin: '*', // Restrict in production
|
||||
credentials: true,
|
||||
methods: ['GET','POST','PUT','PATCH','DELETE'],
|
||||
maxAge: 600,
|
||||
}));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Strategies
|
||||
- **Fixed window**: N requests per time window (simple, bursty at boundaries)
|
||||
- **Sliding window**: Smooth rate enforcement (recommended)
|
||||
- **Token bucket**: Allows controlled bursts
|
||||
|
||||
### Response Headers
|
||||
- `X-RateLimit-Limit`: Maximum requests allowed
|
||||
- `X-RateLimit-Remaining`: Requests remaining in window
|
||||
- `X-RateLimit-Reset`: Timestamp when limit resets
|
||||
|
||||
### Production Notes
|
||||
- Use Redis as backend store for distributed rate limiting
|
||||
- In-memory stores do not work with multiple server instances
|
||||
- Consider different limits for authenticated vs anonymous users
|
||||
|
||||
---
|
||||
|
||||
## Logging Middleware
|
||||
|
||||
### Structured Logging Fields
|
||||
Every request log entry should include:
|
||||
- `request_id`: Unique identifier for tracing
|
||||
- `method`: HTTP method
|
||||
- `path`: Request path
|
||||
- `status_code`: Response status
|
||||
- `duration_ms`: Processing time
|
||||
- `client_ip`: Client IP address
|
||||
- `user_id`: Authenticated user ID (if available)
|
||||
|
||||
### Sensitive Field Masking
|
||||
Never log: `Authorization` header values, request bodies containing `password`, `token`, `secret`, `credit_card` fields.
|
||||
|
||||
---
|
||||
|
||||
## Error Handler
|
||||
|
||||
### Standard Error Response
|
||||
All errors must produce consistent JSON:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human-readable message",
|
||||
"request_id": "abc-123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Exception Mapping
|
||||
- Validation errors: 422 with field-level details
|
||||
- Not found: 404 with resource type and ID
|
||||
- Authentication: 401 with generic message (no details)
|
||||
- Authorization: 403 with required permission
|
||||
- Conflict: 409 with conflicting field
|
||||
- Internal: 500 with request_id only (no stack traces in production)
|
||||
125
plugins/saas-api-platform/skills/openapi-conventions.md
Normal file
125
plugins/saas-api-platform/skills/openapi-conventions.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: openapi-conventions
|
||||
description: OpenAPI 3.x spec generation rules, path naming, schema definitions, response codes
|
||||
---
|
||||
|
||||
# OpenAPI Conventions
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines rules and patterns for generating and validating OpenAPI 3.x specifications. This skill ensures consistency between generated specs and industry best practices.
|
||||
|
||||
---
|
||||
|
||||
## Specification Structure
|
||||
|
||||
An OpenAPI 3.0.3 document must include:
|
||||
|
||||
```yaml
|
||||
openapi: "3.0.3"
|
||||
info:
|
||||
title: <project name>
|
||||
version: <project version>
|
||||
description: <project description>
|
||||
servers:
|
||||
- url: <base url>
|
||||
description: <environment name>
|
||||
paths:
|
||||
/<resource>: ...
|
||||
components:
|
||||
schemas: ...
|
||||
securitySchemes: ...
|
||||
tags: ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Path Naming Rules
|
||||
|
||||
| Rule | Example | Anti-Pattern |
|
||||
|------|---------|-------------|
|
||||
| Plural nouns for collections | `/users` | `/user`, `/getUsers` |
|
||||
| Lowercase with hyphens | `/order-items` | `/orderItems`, `/order_items` |
|
||||
| Resource ID in path | `/users/{user_id}` | `/users?id=123` |
|
||||
| Nested resources max 2 levels | `/users/{id}/orders` | `/users/{id}/orders/{oid}/items/{iid}` |
|
||||
| No verbs in paths | `/users` + POST | `/createUser` |
|
||||
| Version prefix when configured | `/v1/users` | `/api/v1/users` (redundant) |
|
||||
|
||||
---
|
||||
|
||||
## Response Code Standards
|
||||
|
||||
| Method | Success | Client Error | Server Error |
|
||||
|--------|---------|-------------|-------------|
|
||||
| GET (single) | 200 | 404 | 500 |
|
||||
| GET (list) | 200 | 400 (bad params) | 500 |
|
||||
| POST | 201 | 400, 409 (conflict), 422 | 500 |
|
||||
| PUT | 200 | 400, 404, 422 | 500 |
|
||||
| PATCH | 200 | 400, 404, 422 | 500 |
|
||||
| DELETE | 204 | 404 | 500 |
|
||||
|
||||
All endpoints should also document 401 (unauthorized) and 403 (forbidden) when auth is required.
|
||||
|
||||
---
|
||||
|
||||
## Schema Definition Rules
|
||||
|
||||
1. **Naming**: PascalCase for schema names (`UserCreate`, `OrderResponse`)
|
||||
2. **Reuse**: Use `$ref` for shared schemas instead of duplication
|
||||
3. **Required fields**: Explicitly list required fields; do not rely on defaults
|
||||
4. **Types**: Use specific types (`integer` not `number` for IDs; `string` with `format: date-time` for timestamps)
|
||||
5. **Descriptions**: Every property should have a `description` field
|
||||
6. **Examples**: Include `example` values for key properties
|
||||
7. **Nullable**: Use `nullable: true` explicitly when fields can be null
|
||||
|
||||
---
|
||||
|
||||
## Pagination Schema
|
||||
|
||||
List endpoints must return a paginated wrapper:
|
||||
|
||||
```yaml
|
||||
PaginatedResponse:
|
||||
type: object
|
||||
properties:
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ResourceResponse'
|
||||
total:
|
||||
type: integer
|
||||
description: Total number of items
|
||||
page:
|
||||
type: integer
|
||||
description: Current page number
|
||||
page_size:
|
||||
type: integer
|
||||
description: Items per page
|
||||
pages:
|
||||
type: integer
|
||||
description: Total number of pages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Scheme Patterns
|
||||
|
||||
**JWT Bearer:**
|
||||
```yaml
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
```
|
||||
|
||||
**API Key:**
|
||||
```yaml
|
||||
securitySchemes:
|
||||
ApiKeyAuth:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: X-API-Key
|
||||
```
|
||||
|
||||
Apply globally or per-operation using the `security` field.
|
||||
112
plugins/saas-api-platform/skills/route-patterns.md
Normal file
112
plugins/saas-api-platform/skills/route-patterns.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: route-patterns
|
||||
description: RESTful naming, versioning, pagination, filtering, and sorting conventions
|
||||
---
|
||||
|
||||
# Route Patterns
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines standard patterns for RESTful route design. This skill is loaded during scaffolding and validation to ensure generated routes follow consistent, industry-standard conventions.
|
||||
|
||||
---
|
||||
|
||||
## RESTful Resource Naming
|
||||
|
||||
| Pattern | URL | Method | Purpose |
|
||||
|---------|-----|--------|---------|
|
||||
| List | `/{resource}` | GET | Retrieve paginated collection |
|
||||
| Create | `/{resource}` | POST | Create new resource |
|
||||
| Get | `/{resource}/{id}` | GET | Retrieve single resource |
|
||||
| Replace | `/{resource}/{id}` | PUT | Full replacement of resource |
|
||||
| Update | `/{resource}/{id}` | PATCH | Partial update |
|
||||
| Delete | `/{resource}/{id}` | DELETE | Remove resource |
|
||||
|
||||
### Nested Resources
|
||||
|
||||
For parent-child relationships (max 2 levels deep):
|
||||
|
||||
| Pattern | URL | Example |
|
||||
|---------|-----|---------|
|
||||
| Child list | `/{parent}/{parent_id}/{child}` | `/users/42/orders` |
|
||||
| Child create | `/{parent}/{parent_id}/{child}` | POST `/users/42/orders` |
|
||||
| Child get | `/{parent}/{parent_id}/{child}/{child_id}` | `/users/42/orders/7` |
|
||||
|
||||
Beyond 2 levels, flatten with query filters: `/items?order_id=7&user_id=42`
|
||||
|
||||
---
|
||||
|
||||
## Versioning
|
||||
|
||||
| Strategy | Format | Example |
|
||||
|----------|--------|---------|
|
||||
| URL prefix (recommended) | `/v{N}/` | `/v1/users`, `/v2/users` |
|
||||
| Header-based | `Accept: application/vnd.api.v1+json` | Header value |
|
||||
| Query param (discouraged) | `?version=1` | `/users?version=1` |
|
||||
|
||||
URL prefix versioning is the default. Only bump major version for breaking changes.
|
||||
|
||||
---
|
||||
|
||||
## Pagination
|
||||
|
||||
All list endpoints must support pagination:
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `page` | integer | 1 | Page number (1-indexed) |
|
||||
| `page_size` | integer | 20 | Items per page (max 100) |
|
||||
|
||||
Response must include pagination metadata:
|
||||
```json
|
||||
{
|
||||
"items": [...],
|
||||
"total": 142,
|
||||
"page": 2,
|
||||
"page_size": 20,
|
||||
"pages": 8
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Filtering
|
||||
|
||||
Use query parameters for filtering:
|
||||
|
||||
| Pattern | Example | Description |
|
||||
|---------|---------|-------------|
|
||||
| Exact match | `?status=active` | Field equals value |
|
||||
| Multiple values | `?status=active,pending` | Field in list |
|
||||
| Range | `?created_after=2024-01-01&created_before=2024-12-31` | Date/number range |
|
||||
| Search | `?q=search+term` | Full-text search |
|
||||
|
||||
---
|
||||
|
||||
## Sorting
|
||||
|
||||
| Parameter | Format | Example |
|
||||
|-----------|--------|---------|
|
||||
| `sort` | `field` (asc) or `-field` (desc) | `?sort=-created_at` |
|
||||
| Multiple | Comma-separated | `?sort=-created_at,name` |
|
||||
|
||||
---
|
||||
|
||||
## Error Response Format
|
||||
|
||||
All errors must use a consistent structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Human-readable description",
|
||||
"details": [
|
||||
{"field": "email", "message": "Invalid email format"}
|
||||
],
|
||||
"request_id": "abc-123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Error codes should be uppercase snake_case constants: `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR`, `CONFLICT`, `INTERNAL_ERROR`.
|
||||
49
plugins/saas-api-platform/skills/visual-header.md
Normal file
49
plugins/saas-api-platform/skills/visual-header.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: visual-header
|
||||
description: Standard header format for API platform commands and agents
|
||||
---
|
||||
|
||||
# Visual Header
|
||||
|
||||
## Standard Format
|
||||
|
||||
Display at the start of every command execution:
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| API-PLATFORM - [Command Name] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Command Headers
|
||||
|
||||
| Command | Header Text |
|
||||
|---------|-------------|
|
||||
| api-setup | Setup Wizard |
|
||||
| api-scaffold | Scaffold |
|
||||
| api-validate | Validate |
|
||||
| api-docs | Docs |
|
||||
| api-test-routes | Test Routes |
|
||||
| api-middleware | Middleware |
|
||||
|
||||
## Summary Box Format
|
||||
|
||||
For completion summaries:
|
||||
|
||||
```
|
||||
+============================================================+
|
||||
| API-PLATFORM [OPERATION] COMPLETE |
|
||||
+============================================================+
|
||||
| Component: [Status] |
|
||||
| Component: [Status] |
|
||||
+============================================================+
|
||||
```
|
||||
|
||||
## Status Indicators
|
||||
|
||||
- Success: `[check]` or `Ready`
|
||||
- Warning: `[!]` or `Partial`
|
||||
- Failure: `[X]` or `Failed`
|
||||
- New file: `[+]`
|
||||
- Modified file: `[~]`
|
||||
- Deleted file: `[-]`
|
||||
Reference in New Issue
Block a user