codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/api-design/examples/error-response.json

@@ -0,0 +1,159 @@
+{
+  "_comment": "Standard API error response examples. Use these as templates for consistent error formatting.",
+
+  "validation_error": {
+    "status": 400,
+    "body": {
+      "error": {
+        "code": "VALIDATION_ERROR",
+        "message": "Invalid input data",
+        "details": [
+          {
+            "field": "email",
+            "message": "Must be a valid email address",
+            "code": "INVALID_FORMAT"
+          },
+          {
+            "field": "name",
+            "message": "Name is required",
+            "code": "REQUIRED"
+          },
+          {
+            "field": "age",
+            "message": "Must be between 1 and 150",
+            "code": "OUT_OF_RANGE"
+          }
+        ]
+      },
+      "meta": {
+        "requestId": "req_abc123",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "unauthorized": {
+    "status": 401,
+    "body": {
+      "error": {
+        "code": "UNAUTHORIZED",
+        "message": "Authentication is required to access this resource"
+      },
+      "meta": {
+        "requestId": "req_def456",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "forbidden": {
+    "status": 403,
+    "body": {
+      "error": {
+        "code": "FORBIDDEN",
+        "message": "You do not have permission to perform this action",
+        "details": [
+          {
+            "field": "role",
+            "message": "Requires 'admin' role",
+            "code": "INSUFFICIENT_PERMISSIONS"
+          }
+        ]
+      },
+      "meta": {
+        "requestId": "req_ghi789",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "not_found": {
+    "status": 404,
+    "body": {
+      "error": {
+        "code": "NOT_FOUND",
+        "message": "The requested resource was not found"
+      },
+      "meta": {
+        "requestId": "req_jkl012",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "conflict": {
+    "status": 409,
+    "body": {
+      "error": {
+        "code": "CONFLICT",
+        "message": "A resource with this identifier already exists",
+        "details": [
+          {
+            "field": "email",
+            "message": "An account with this email already exists",
+            "code": "DUPLICATE"
+          }
+        ]
+      },
+      "meta": {
+        "requestId": "req_mno345",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "rate_limited": {
+    "status": 429,
+    "headers": {
+      "Retry-After": "60",
+      "X-RateLimit-Limit": "100",
+      "X-RateLimit-Remaining": "0",
+      "X-RateLimit-Reset": "1705312260"
+    },
+    "body": {
+      "error": {
+        "code": "RATE_LIMITED",
+        "message": "Too many requests. Please retry after 60 seconds."
+      },
+      "meta": {
+        "requestId": "req_pqr678",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "internal_error": {
+    "status": 500,
+    "body": {
+      "error": {
+        "code": "INTERNAL_ERROR",
+        "message": "An unexpected error occurred. Please try again later."
+      },
+      "meta": {
+        "requestId": "req_stu901",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+
+  "_error_code_registry": {
+    "_comment": "Machine-readable error codes used across the API. Keep this list updated.",
+    "codes": {
+      "VALIDATION_ERROR": "Request body or parameters failed validation",
+      "UNAUTHORIZED": "Missing or invalid authentication credentials",
+      "FORBIDDEN": "Valid credentials but insufficient permissions",
+      "NOT_FOUND": "Requested resource does not exist",
+      "CONFLICT": "Request conflicts with current server state",
+      "RATE_LIMITED": "Client exceeded rate limit quota",
+      "INTERNAL_ERROR": "Unexpected server-side failure",
+      "SERVICE_UNAVAILABLE": "Upstream dependency is unavailable",
+      "REQUIRED": "A required field is missing",
+      "INVALID_FORMAT": "Field value does not match expected format",
+      "OUT_OF_RANGE": "Numeric value outside allowed range",
+      "DUPLICATE": "Value must be unique but already exists",
+      "INSUFFICIENT_PERMISSIONS": "Specific permission check failed",
+      "EXPIRED": "Token or resource has expired",
+      "IMMUTABLE": "Attempted to modify a read-only field"
+    }
+  }
+}

package/.ai-rules/skills/api-design/examples/openapi-template.yaml

@@ -0,0 +1,393 @@
+# OpenAPI 3.1 Template
+# Copy and adapt this template when creating new API specifications.
+# Replace all placeholder values (marked with <angle-brackets>).
+
+openapi: 3.1.0
+info:
+  title: <Service Name> API
+  version: 1.0.0
+  description: |
+    <Brief description of what this API does and who it serves.>
+  contact:
+    name: <Team Name>
+    email: <team@example.com>
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://api-staging.example.com/v1
+    description: Staging
+
+# ──────────────────────────────────────────
+# Paths
+# ──────────────────────────────────────────
+
+paths:
+  /items:
+    get:
+      summary: List items
+      operationId: listItems
+      tags: [Items]
+      parameters:
+        - $ref: '#/components/parameters/PageParam'
+        - $ref: '#/components/parameters/PageSizeParam'
+        - name: status
+          in: query
+          description: Filter by item status
+          schema:
+            type: string
+            enum: [active, archived, draft]
+        - name: search
+          in: query
+          description: Full-text search across name and description
+          schema:
+            type: string
+            maxLength: 200
+      responses:
+        '200':
+          description: Paginated list of items
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    post:
+      summary: Create an item
+      operationId: createItem
+      tags: [Items]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateItemRequest'
+      responses:
+        '201':
+          description: Item created
+          headers:
+            Location:
+              description: URL of the newly created item
+              schema:
+                type: string
+                format: uri
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /items/{itemId}:
+    parameters:
+      - name: itemId
+        in: path
+        required: true
+        description: Unique item identifier
+        schema:
+          type: string
+          format: uuid
+
+    get:
+      summary: Get an item by ID
+      operationId: getItem
+      tags: [Items]
+      responses:
+        '200':
+          description: Item details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    patch:
+      summary: Update an item
+      operationId: updateItem
+      tags: [Items]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateItemRequest'
+      responses:
+        '200':
+          description: Item updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+    delete:
+      summary: Delete an item
+      operationId: deleteItem
+      tags: [Items]
+      responses:
+        '204':
+          description: Item deleted
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+# ──────────────────────────────────────────
+# Components
+# ──────────────────────────────────────────
+
+components:
+  # --- Schemas ---
+
+  schemas:
+    Item:
+      type: object
+      required: [id, name, status, createdAt, updatedAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier
+          examples: ['550e8400-e29b-41d4-a716-446655440000']
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: Display name
+        description:
+          type: string
+          maxLength: 2000
+          description: Detailed description
+        status:
+          type: string
+          enum: [active, archived, draft]
+          description: Current item status
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    CreateItemRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        description:
+          type: string
+          maxLength: 2000
+        status:
+          type: string
+          enum: [active, draft]
+          default: draft
+
+    UpdateItemRequest:
+      type: object
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        description:
+          type: string
+          maxLength: 2000
+        status:
+          type: string
+          enum: [active, archived, draft]
+
+    ItemResponse:
+      type: object
+      required: [data, meta]
+      properties:
+        data:
+          $ref: '#/components/schemas/Item'
+        meta:
+          $ref: '#/components/schemas/ResponseMeta'
+
+    ItemListResponse:
+      type: object
+      required: [data, meta]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Item'
+        meta:
+          allOf:
+            - $ref: '#/components/schemas/ResponseMeta'
+            - $ref: '#/components/schemas/PaginationMeta'
+
+    # --- Shared Schemas ---
+
+    ResponseMeta:
+      type: object
+      required: [requestId, timestamp]
+      properties:
+        requestId:
+          type: string
+          format: uuid
+          description: Unique request trace ID
+        timestamp:
+          type: string
+          format: date-time
+
+    PaginationMeta:
+      type: object
+      required: [total, page, pageSize, hasNext]
+      properties:
+        total:
+          type: integer
+          minimum: 0
+        page:
+          type: integer
+          minimum: 1
+        pageSize:
+          type: integer
+          minimum: 1
+          maximum: 100
+        hasNext:
+          type: boolean
+
+    ErrorResponse:
+      type: object
+      required: [error, meta]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+              description: Machine-readable error code
+              examples: ['VALIDATION_ERROR']
+            message:
+              type: string
+              description: Human-readable error message
+            details:
+              type: array
+              items:
+                type: object
+                required: [message]
+                properties:
+                  field:
+                    type: string
+                  message:
+                    type: string
+                  code:
+                    type: string
+        meta:
+          $ref: '#/components/schemas/ResponseMeta'
+
+  # --- Parameters ---
+
+  parameters:
+    PageParam:
+      name: page
+      in: query
+      description: Page number (1-indexed)
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+
+    PageSizeParam:
+      name: pageSize
+      in: query
+      description: Items per page
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 20
+
+  # --- Responses ---
+
+  responses:
+    ValidationError:
+      description: Input validation failed
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: VALIDATION_ERROR
+              message: Invalid input data
+              details:
+                - field: name
+                  message: Name is required
+                  code: REQUIRED
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: NOT_FOUND
+              message: The requested resource was not found
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: UNAUTHORIZED
+              message: Authentication is required
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+    Conflict:
+      description: State conflict (duplicate or version mismatch)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: CONFLICT
+              message: An item with this name already exists
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+  # --- Security ---
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []
+
+tags:
+  - name: Items
+    description: Item management endpoints