javi-forge 1.1.0 → 1.3.0

package/ai-config/skills/backend/chi-router/SKILL.md

@@ -1,396 +0,0 @@
----
-name: chi-router
-description: >
-  Go HTTP router patterns with Chi v5 - routing, middleware, handlers.
-  Trigger: chi, go router, http handlers, go middleware, rest api go
-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-metadata:
-  author: plataforma-industrial
-  version: "2.0"
-  tags: [go, chi, http, router, backend]
-  updated: "2026-02"
----
-
-# Chi Router Skill
-
-Go HTTP router patterns using Chi v5 for REST APIs.
-
-## Stack
-
-```go
-require (
-    github.com/go-chi/chi/v5 v5.0.12
-    github.com/go-chi/cors v1.2.1
-    github.com/go-chi/httprate v0.9.0
-    github.com/go-chi/render v1.0.3
-)
-```
-
-## Project Structure
-
-```
-apps/api/
-├── cmd/api/main.go
-├── internal/
-│   ├── config/config.go
-│   ├── handler/
-│   │   ├── handler.go
-│   │   ├── resource_handler.go
-│   │   └── response.go
-│   ├── middleware/
-│   │   ├── auth.go
-│   │   ├── tenant.go
-│   │   └── logging.go
-│   ├── router/router.go
-│   ├── service/
-│   └── repository/
-└── go.mod
-```
-
-## Router Setup
-
-```go
-package router
-
-import (
-    "time"
-    "github.com/go-chi/chi/v5"
-    "github.com/go-chi/chi/v5/middleware"
-    "github.com/go-chi/cors"
-    "github.com/go-chi/httprate"
-)
-
-func New(handlers *Handlers, cfg *config.Config) *chi.Mux {
-    r := chi.NewRouter()
-
-    // Global middleware
-    r.Use(middleware.RequestID)
-    r.Use(middleware.RealIP)
-    r.Use(middleware.Logger)
-    r.Use(middleware.Recoverer)
-    r.Use(middleware.Timeout(30 * time.Second))
-
-    // CORS
-    r.Use(cors.Handler(cors.Options{
-        AllowedOrigins:   cfg.CORSOrigins,
-        AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
-        AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type"},
-        AllowCredentials: true,
-        MaxAge:           300,
-    }))
-
-    // Rate limiting
-    r.Use(httprate.LimitByIP(100, time.Minute))
-
-    // Health (no auth)
-    r.Get("/health", handlers.Health.Live)
-
-    // API v1
-    r.Route("/api/v1", func(r chi.Router) {
-        // Public
-        r.Post("/auth/login", handlers.Auth.Login)
-
-        // Protected
-        r.Group(func(r chi.Router) {
-            r.Use(JWTAuthMiddleware(cfg.JWTSecret))
-            r.Use(TenantMiddleware)
-
-            r.Route("/resources", func(r chi.Router) {
-                r.Get("/", handlers.Resource.List)
-                r.Post("/", handlers.Resource.Create)
-                r.Route("/{resourceID}", func(r chi.Router) {
-                    r.Use(ResourceCtx)
-                    r.Get("/", handlers.Resource.Get)
-                    r.Put("/", handlers.Resource.Update)
-                    r.Delete("/", handlers.Resource.Delete)
-                })
-            })
-        })
-    })
-
-    return r
-}
-```
-
-## Handler Pattern
-
-```go
-package handler
-
-import (
-    "encoding/json"
-    "net/http"
-    "github.com/go-chi/chi/v5"
-)
-
-type ResourceHandler struct {
-    service *service.ResourceService
-}
-
-func NewResourceHandler(svc *service.ResourceService) *ResourceHandler {
-    return &ResourceHandler{service: svc}
-}
-
-func (h *ResourceHandler) List(w http.ResponseWriter, r *http.Request) {
-    ctx := r.Context()
-    tenantID := TenantFromContext(ctx)
-
-    filters := &Filters{
-        Status: r.URL.Query().Get("status"),
-        Page:   parseIntOrDefault(r.URL.Query().Get("page"), 1),
-        Limit:  parseIntOrDefault(r.URL.Query().Get("limit"), 20),
-    }
-
-    items, total, err := h.service.List(ctx, tenantID, filters)
-    if err != nil {
-        respondError(w, http.StatusInternalServerError, "failed to list")
-        return
-    }
-
-    respondPaginated(w, items, total, filters.Page, filters.Limit)
-}
-
-func (h *ResourceHandler) Create(w http.ResponseWriter, r *http.Request) {
-    ctx := r.Context()
-    tenantID := TenantFromContext(ctx)
-
-    var input CreateInput
-    if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
-        respondError(w, http.StatusBadRequest, "invalid json")
-        return
-    }
-
-    if err := input.Validate(); err != nil {
-        respondValidationError(w, err)
-        return
-    }
-
-    item, err := h.service.Create(ctx, tenantID, &input)
-    if err != nil {
-        respondError(w, http.StatusInternalServerError, "failed to create")
-        return
-    }
-
-    respondJSON(w, http.StatusCreated, DataResponse{Data: item})
-}
-
-func (h *ResourceHandler) Get(w http.ResponseWriter, r *http.Request) {
-    resource := ResourceFromContext(r.Context())
-    respondJSON(w, http.StatusOK, DataResponse{Data: resource})
-}
-```
-
-## JWT Middleware
-
-```go
-package middleware
-
-import (
-    "context"
-    "net/http"
-    "strings"
-    "github.com/golang-jwt/jwt/v5"
-)
-
-type contextKey string
-
-const (
-    ClaimsKey contextKey = "claims"
-    UserIDKey contextKey = "userID"
-    TenantKey contextKey = "tenantID"
-)
-
-func JWTAuthMiddleware(secret string) func(next http.Handler) http.Handler {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            authHeader := r.Header.Get("Authorization")
-            if authHeader == "" {
-                respondError(w, http.StatusUnauthorized, "missing authorization")
-                return
-            }
-
-            parts := strings.Split(authHeader, " ")
-            if len(parts) != 2 || parts[0] != "Bearer" {
-                respondError(w, http.StatusUnauthorized, "invalid authorization")
-                return
-            }
-
-            token, err := jwt.Parse(parts[1], func(token *jwt.Token) (interface{}, error) {
-                if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
-                    return nil, fmt.Errorf("unexpected signing method")
-                }
-                return []byte(secret), nil
-            })
-
-            if err != nil || !token.Valid {
-                respondError(w, http.StatusUnauthorized, "invalid token")
-                return
-            }
-
-            claims := token.Claims.(jwt.MapClaims)
-            ctx := context.WithValue(r.Context(), ClaimsKey, claims)
-            ctx = context.WithValue(ctx, UserIDKey, claims["sub"].(string))
-
-            next.ServeHTTP(w, r.WithContext(ctx))
-        })
-    }
-}
-
-func UserIDFromContext(ctx context.Context) string {
-    if v := ctx.Value(UserIDKey); v != nil {
-        return v.(string)
-    }
-    return ""
-}
-```
-
-## Resource Context Middleware
-
-```go
-func ResourceCtx(next http.Handler) http.Handler {
-    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-        resourceID := chi.URLParam(r, "resourceID")
-
-        id, err := uuid.Parse(resourceID)
-        if err != nil {
-            respondError(w, http.StatusBadRequest, "invalid id")
-            return
-        }
-
-        tenantID := TenantFromContext(r.Context())
-        resource, err := resourceService.GetByID(r.Context(), tenantID, id)
-        if err != nil {
-            respondError(w, http.StatusNotFound, "not found")
-            return
-        }
-
-        ctx := context.WithValue(r.Context(), resourceContextKey{}, resource)
-        next.ServeHTTP(w, r.WithContext(ctx))
-    })
-}
-```
-
-## Response Helpers
-
-```go
-package handler
-
-type DataResponse struct {
-    Data interface{} `json:"data"`
-}
-
-type ErrorResponse struct {
-    Error   string            `json:"error"`
-    Code    string            `json:"code,omitempty"`
-    Details map[string]string `json:"details,omitempty"`
-}
-
-type PaginatedResponse struct {
-    Data interface{} `json:"data"`
-    Meta Meta        `json:"meta"`
-}
-
-type Meta struct {
-    Total      int `json:"total"`
-    Page       int `json:"page"`
-    Limit      int `json:"limit"`
-    TotalPages int `json:"totalPages"`
-}
-
-func respondJSON(w http.ResponseWriter, status int, data interface{}) {
-    w.Header().Set("Content-Type", "application/json")
-    w.WriteHeader(status)
-    json.NewEncoder(w).Encode(data)
-}
-
-func respondError(w http.ResponseWriter, status int, message string) {
-    respondJSON(w, status, ErrorResponse{Error: message})
-}
-
-func respondPaginated(w http.ResponseWriter, data interface{}, total, page, limit int) {
-    totalPages := (total + limit - 1) / limit
-    respondJSON(w, http.StatusOK, PaginatedResponse{
-        Data: data,
-        Meta: Meta{Total: total, Page: page, Limit: limit, TotalPages: totalPages},
-    })
-}
-```
-
-## Route Patterns
-
-```go
-// Middleware per group
-r.Group(func(r chi.Router) {
-    r.Use(AuthMiddleware)
-    r.Get("/protected", handler)
-})
-
-// Middleware per route
-r.With(RateLimitMiddleware).Post("/login", handler)
-
-// Mount subrouters
-r.Mount("/api/v1/resources", ResourceRouter(handler))
-
-// Get URL param
-id := chi.URLParam(r, "id")
-
-// Get query param
-status := r.URL.Query().Get("status")
-
-// Route context
-rctx := chi.RouteContext(r.Context())
-pattern := rctx.RoutePattern()
-```
-
-## Testing
-
-```go
-func TestHandler_List(t *testing.T) {
-    mockService := &MockService{}
-    handler := NewHandler(mockService)
-
-    mockService.On("List", mock.Anything, mock.Anything).Return(
-        []*model.Item{{ID: "1", Name: "Test"}}, 1, nil,
-    )
-
-    req := httptest.NewRequest("GET", "/api/v1/resources", nil)
-    req = req.WithContext(context.WithValue(req.Context(), TenantKey, "tenant-1"))
-    rec := httptest.NewRecorder()
-
-    handler.List(rec, req)
-
-    assert.Equal(t, http.StatusOK, rec.Code)
-}
-
-func TestRoutes(t *testing.T) {
-    r := chi.NewRouter()
-    r.Use(testAuthMiddleware)
-    r.Route("/api/v1/resources", func(r chi.Router) {
-        r.Get("/", handler.List)
-        r.Get("/{id}", handler.Get)
-    })
-
-    req := httptest.NewRequest("GET", "/api/v1/resources", nil)
-    rec := httptest.NewRecorder()
-    r.ServeHTTP(rec, req)
-    assert.Equal(t, http.StatusOK, rec.Code)
-}
-```
-
-## Best Practices
-
-1. **Middleware levels**: Global for logging, group for auth, route for rate limiting
-2. **Resource context pattern**: Load and validate resources in middleware
-3. **Consistent responses**: Always use helper functions
-4. **Validate input**: Decode JSON, then validate before processing
-
-## Related Skills
-
-- `pgx-postgres`: Database access patterns
-- `jwt-auth`: Auth middleware integration
-- `redis-cache`: Response caching
-- `opentelemetry`: Distributed tracing

package/ai-config/skills/backend/error-handling/SKILL.md

@@ -1,255 +0,0 @@
----
-name: error-handling
-description: >
-  API error handling patterns. RFC 7807 Problem Details, error codes, client handling.
-  Trigger: error handling, exceptions, problem details, RFC 7807, error response
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [errors, exceptions, api-design, standards]
-  scope: ["**/exceptions/**", "**/error/**"]
----
-
-# Error Handling Concepts
-
-## RFC 7807 Problem Details
-
-```json
-{
-  "type": "https://api.example.com/errors/validation",
-  "title": "Validation Error",
-  "status": 400,
-  "detail": "The request contains invalid data",
-  "instance": "/api/users/123",
-  "errors": [
-    {
-      "field": "email",
-      "message": "Invalid email format"
-    }
-  ]
-}
-```
-
-### Required Fields
-```
-type: URI identifying the error type (documentation link)
-title: Human-readable summary (stable, not localized)
-status: HTTP status code
-```
-
-### Optional Fields
-```
-detail: Human-readable explanation (may vary per occurrence)
-instance: URI identifying the specific occurrence
-<extensions>: Custom fields for additional context
-```
-
-## Error Categorization
-
-### Client Errors (4xx)
-```
-400 Bad Request
-- Malformed syntax
-- Invalid field values
-- Missing required fields
-
-401 Unauthorized
-- Missing authentication
-- Expired token
-- Invalid credentials
-
-403 Forbidden
-- Valid auth but insufficient permissions
-- Resource access denied
-- Rate limit exceeded (also 429)
-
-404 Not Found
-- Resource doesn't exist
-- Endpoint not found
-- Soft-deleted resource
-
-409 Conflict
-- Duplicate resource
-- Optimistic locking failure
-- State conflict
-
-422 Unprocessable Entity
-- Semantic errors
-- Business rule violations
-- Validation errors (alternative to 400)
-```
-
-### Server Errors (5xx)
-```
-500 Internal Server Error
-- Unexpected exceptions
-- Programming errors
-- Configuration issues
-
-502 Bad Gateway
-- Upstream service failure
-- Invalid upstream response
-
-503 Service Unavailable
-- Maintenance mode
-- Overloaded
-- Circuit breaker open
-
-504 Gateway Timeout
-- Upstream timeout
-- Slow dependency
-```
-
-## Error Code System
-
-```
-Format: DOMAIN-CATEGORY-NUMBER
-
-Examples:
-AUTH-TOKEN-001: Token expired
-AUTH-TOKEN-002: Token invalid
-AUTH-TOKEN-003: Token revoked
-
-USER-VAL-001: Email already exists
-USER-VAL-002: Password too weak
-USER-VAL-003: Invalid phone format
-
-ORDER-BIZ-001: Insufficient inventory
-ORDER-BIZ-002: Shipping address invalid
-ORDER-BIZ-003: Payment declined
-```
-
-## Error Response Patterns
-
-### Validation Errors
-```json
-{
-  "type": "https://api.example.com/errors/validation",
-  "title": "Validation Failed",
-  "status": 400,
-  "detail": "2 validation errors occurred",
-  "errors": [
-    {
-      "field": "email",
-      "code": "USER-VAL-001",
-      "message": "Email is already registered",
-      "rejectedValue": "test@example.com"
-    },
-    {
-      "field": "password",
-      "code": "USER-VAL-002",
-      "message": "Password must be at least 8 characters",
-      "rejectedValue": null
-    }
-  ]
-}
-```
-
-### Business Logic Errors
-```json
-{
-  "type": "https://api.example.com/errors/business",
-  "title": "Business Rule Violation",
-  "status": 422,
-  "detail": "Cannot complete order",
-  "code": "ORDER-BIZ-001",
-  "context": {
-    "requiredStock": 10,
-    "availableStock": 3,
-    "productId": "PROD-123"
-  }
-}
-```
-
-### Authentication Errors
-```json
-{
-  "type": "https://api.example.com/errors/authentication",
-  "title": "Authentication Failed",
-  "status": 401,
-  "detail": "Token has expired",
-  "code": "AUTH-TOKEN-001",
-  "expiredAt": "2024-01-15T10:30:00Z",
-  "refreshable": true
-}
-```
-
-## Client Error Handling
-
-### Retry Strategy
-```
-Retryable errors:
-- 429 Too Many Requests (with backoff)
-- 500 Internal Server Error (limited)
-- 502 Bad Gateway
-- 503 Service Unavailable
-- 504 Gateway Timeout
-
-Non-retryable:
-- 400 Bad Request
-- 401 Unauthorized
-- 403 Forbidden
-- 404 Not Found
-- 409 Conflict
-- 422 Unprocessable Entity
-```
-
-### Exponential Backoff
-```
-Attempt 1: Wait 1 second
-Attempt 2: Wait 2 seconds
-Attempt 3: Wait 4 seconds
-Attempt 4: Wait 8 seconds
-...with jitter to prevent thundering herd
-```
-
-## Logging Strategy
-
-```
-Log levels by error type:
-
-ERROR (investigate immediately):
-- 500 Internal Server Error
-- Unhandled exceptions
-- Data corruption
-
-WARN (monitor trends):
-- 401/403 authentication failures
-- 409 conflicts
-- Circuit breaker trips
-
-INFO (normal operations):
-- 400/422 validation errors
-- 404 not found
-- Rate limiting
-
-DEBUG (troubleshooting):
-- Full request/response
-- Stack traces
-- Context details
-```
-
-## Security Considerations
-
-```
-Never expose:
-- Stack traces to clients
-- Internal paths or class names
-- Database error details
-- System configuration
-
-Always:
-- Use generic messages for auth errors
-- Log full details server-side
-- Correlate with request ID
-- Rate limit error responses
-```
-
-## Related Skills
-
-- `exceptions-spring`: Spring Boot exception handling