javi-forge 0.1.0

package/ai-config/skills/backend/exceptions-spring/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: exceptions-spring
+description: >
+  Spring Boot exception handling. @ControllerAdvice, ProblemDetail, GlobalExceptionHandler.
+  Trigger: apigen-exceptions, GlobalExceptionHandler, @ControllerAdvice, ProblemDetail
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+metadata:
+  author: apigen-team
+  version: "1.0"
+  tags: [exceptions, spring-boot, error-handling, java]
+  scope: ["apigen-exceptions/**", "apigen-core/**/exception/**"]
+---
+
+# Exceptions Spring Boot (apigen-exceptions)
+
+## Configuration
+
+```yaml
+apigen:
+  exceptions:
+    include-stack-trace: ${DEBUG:false}
+    include-message: always
+    log-full-details: true
+    problem-base-uri: https://api.example.com/errors
+```
+
+## Base Exception Hierarchy
+
+```java
+public abstract class ApiException extends RuntimeException {
+
+    private final String errorCode;
+    private final HttpStatus status;
+    private final Map<String, Object> context;
+
+    protected ApiException(String message, String errorCode,
+                           HttpStatus status, Map<String, Object> context) {
+        super(message);
+        this.errorCode = errorCode;
+        this.status = status;
+        this.context = context != null ? context : Map.of();
+    }
+
+    public ProblemDetail toProblemDetail(String baseUri) {
+        ProblemDetail problem = ProblemDetail.forStatus(status);
+        problem.setType(URI.create(baseUri + "/" + errorCode));
+        problem.setTitle(getTitle());
+        problem.setDetail(getMessage());
+        problem.setProperty("code", errorCode);
+        context.forEach(problem::setProperty);
+        return problem;
+    }
+
+    protected abstract String getTitle();
+}
+```
+
+## Specific Exception Types
+
+```java
+// Validation exceptions
+public class ValidationException extends ApiException {
+    private final List<FieldError> fieldErrors;
+
+    public ValidationException(List<FieldError> errors) {
+        super("Validation failed", "VAL-001", HttpStatus.BAD_REQUEST,
+              Map.of("errors", errors));
+        this.fieldErrors = errors;
+    }
+
+    @Override
+    protected String getTitle() {
+        return "Validation Error";
+    }
+}
+
+// Resource exceptions
+public class ResourceNotFoundException extends ApiException {
+    public ResourceNotFoundException(String resourceType, Object id) {
+        super(String.format("%s with id '%s' not found", resourceType, id),
+              "RES-404", HttpStatus.NOT_FOUND,
+              Map.of("resourceType", resourceType, "resourceId", id));
+    }
+
+    @Override
+    protected String getTitle() {
+        return "Resource Not Found";
+    }
+}
+
+// Business rule exceptions
+public class BusinessRuleException extends ApiException {
+    public BusinessRuleException(String message, String code,
+                                  Map<String, Object> context) {
+        super(message, code, HttpStatus.UNPROCESSABLE_ENTITY, context);
+    }
+
+    @Override
+    protected String getTitle() {
+        return "Business Rule Violation";
+    }
+}
+
+// Conflict exceptions
+public class ConflictException extends ApiException {
+    public ConflictException(String message, String field, Object value) {
+        super(message, "CONFLICT-409", HttpStatus.CONFLICT,
+              Map.of("field", field, "value", value));
+    }
+
+    @Override
+    protected String getTitle() {
+        return "Resource Conflict";
+    }
+}
+```
+
+## Global Exception Handler
+
+```java
+@RestControllerAdvice
+@Order(Ordered.HIGHEST_PRECEDENCE)
+public class GlobalExceptionHandler {
+
+    private final ExceptionProperties properties;
+    private final MessageSource messageSource;
+
+    @ExceptionHandler(ApiException.class)
+    public ProblemDetail handleApiException(ApiException ex,
+                                             HttpServletRequest request) {
+        log.warn("API Exception: {} - {}", ex.getErrorCode(), ex.getMessage());
+
+        ProblemDetail problem = ex.toProblemDetail(properties.getProblemBaseUri());
+        problem.setInstance(URI.create(request.getRequestURI()));
+        return problem;
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ProblemDetail handleValidation(MethodArgumentNotValidException ex,
+                                           HttpServletRequest request) {
+        List<FieldError> errors = ex.getBindingResult().getFieldErrors()
+            .stream()
+            .map(fe -> new FieldError(fe.getField(),
+                                       fe.getDefaultMessage(),
+                                       fe.getRejectedValue()))
+            .toList();
+
+        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
+        problem.setType(URI.create(properties.getProblemBaseUri() + "/validation"));
+        problem.setTitle("Validation Error");
+        problem.setDetail(errors.size() + " validation errors");
+        problem.setProperty("errors", errors);
+        problem.setInstance(URI.create(request.getRequestURI()));
+        return problem;
+    }
+
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ProblemDetail handleConstraintViolation(
+            ConstraintViolationException ex,
+            HttpServletRequest request) {
+
+        List<FieldError> errors = ex.getConstraintViolations().stream()
+            .map(cv -> new FieldError(
+                getPropertyPath(cv),
+                cv.getMessage(),
+                cv.getInvalidValue()))
+            .toList();
+
+        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
+        problem.setType(URI.create(properties.getProblemBaseUri() + "/validation"));
+        problem.setTitle("Constraint Violation");
+        problem.setProperty("errors", errors);
+        return problem;
+    }
+
+    @ExceptionHandler(DataIntegrityViolationException.class)
+    public ProblemDetail handleDataIntegrity(DataIntegrityViolationException ex) {
+        log.error("Data integrity violation", ex);
+
+        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.CONFLICT);
+        problem.setTitle("Data Conflict");
+        problem.setDetail("A data integrity constraint was violated");
+        // Don't expose DB details
+        return problem;
+    }
+
+    @ExceptionHandler(OptimisticLockingFailureException.class)
+    public ProblemDetail handleOptimisticLock(
+            OptimisticLockingFailureException ex) {
+
+        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.CONFLICT);
+        problem.setTitle("Concurrent Modification");
+        problem.setDetail("Resource was modified by another request");
+        problem.setProperty("code", "OPT-LOCK-001");
+        return problem;
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ProblemDetail handleGeneric(Exception ex, HttpServletRequest request) {
+        String requestId = UUID.randomUUID().toString();
+        log.error("Unhandled exception [requestId={}]", requestId, ex);
+
+        ProblemDetail problem = ProblemDetail.forStatus(
+            HttpStatus.INTERNAL_SERVER_ERROR);
+        problem.setTitle("Internal Server Error");
+        problem.setDetail("An unexpected error occurred");
+        problem.setProperty("requestId", requestId);
+
+        if (properties.isIncludeStackTrace()) {
+            problem.setProperty("stackTrace", getStackTrace(ex));
+        }
+
+        return problem;
+    }
+}
+```
+
+## Field Error Record
+
+```java
+public record FieldError(
+    String field,
+    String message,
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    Object rejectedValue
+) {}
+```
+
+## Exception Auto Configuration
+
+```java
+@AutoConfiguration
+@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
+@EnableConfigurationProperties(ExceptionProperties.class)
+public class ExceptionAutoConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean
+    public GlobalExceptionHandler globalExceptionHandler(
+            ExceptionProperties properties,
+            @Autowired(required = false) MessageSource messageSource) {
+        return new GlobalExceptionHandler(properties, messageSource);
+    }
+
+    @Bean
+    public ProblemDetailExceptionHandler problemDetailHandler() {
+        return new ProblemDetailExceptionHandler();
+    }
+}
+```
+
+## Custom Problem Detail Extensions
+
+```java
+public class ExtendedProblemDetail extends ProblemDetail {
+
+    private String code;
+    private Instant timestamp;
+    private String traceId;
+
+    public static ExtendedProblemDetail forStatusAndCode(
+            HttpStatus status, String code) {
+
+        ExtendedProblemDetail problem = new ExtendedProblemDetail();
+        problem.setStatus(status.value());
+        problem.setCode(code);
+        problem.setTimestamp(Instant.now());
+        problem.setTraceId(MDC.get("traceId"));
+        return problem;
+    }
+}
+```
+
+## Testing Exceptions
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerExceptionTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;
+
+    @Test
+    void shouldReturnProblemDetailForNotFound() throws Exception {
+        when(userService.findById(any()))
+            .thenThrow(new ResourceNotFoundException("User", "123"));
+
+        mockMvc.perform(get("/api/users/123"))
+            .andExpect(status().isNotFound())
+            .andExpect(content().contentType(MediaType.APPLICATION_PROBLEM_JSON))
+            .andExpect(jsonPath("$.type").value(containsString("RES-404")))
+            .andExpect(jsonPath("$.title").value("Resource Not Found"))
+            .andExpect(jsonPath("$.resourceType").value("User"));
+    }
+
+    @Test
+    void shouldReturnValidationErrors() throws Exception {
+        String invalidJson = """
+            {"email": "not-an-email", "name": ""}
+            """;
+
+        mockMvc.perform(post("/api/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(invalidJson))
+            .andExpect(status().isBadRequest())
+            .andExpect(jsonPath("$.errors").isArray())
+            .andExpect(jsonPath("$.errors.length()").value(2));
+    }
+}
+```
+
+## Related Skills
+
+- `error-handling`: Error handling concepts
+- `spring-boot-4`: Spring Boot 4.0 patterns

package/ai-config/skills/backend/fastapi/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: fastapi
+description: >
+  FastAPI development patterns with Pydantic v2, async services, and dependency injection.
+  Trigger: fastapi, python api, async python, pydantic, uvicorn
+tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+metadata:
+  author: plataforma-industrial
+  version: "2.0"
+  tags: [python, fastapi, async, api]
+  updated: "2026-02"
+---
+
+# FastAPI Development Skill
+
+## Stack
+
+```txt
+fastapi==0.110.0
+uvicorn[standard]==0.28.0
+pydantic==2.6.3
+pydantic-settings==2.2.1
+python-jose[cryptography]==3.3.0
+httpx==0.27.0
+redis==5.0.2
+sqlalchemy==2.0.28
+asyncpg==0.29.0
+```
+
+## Project Structure
+
+```
+src/
+└── app_name/
+    ├── __init__.py
+    ├── main.py
+    ├── config.py
+    ├── api/
+    │   ├── deps.py
+    │   └── routes/
+    ├── core/
+    │   ├── security.py
+    │   └── exceptions.py
+    ├── models/
+    ├── services/
+    └── agents/
+```
+
+## Main Application Pattern
+
+```python
+# main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    app.state.cache = CacheService()
+    await app.state.cache.connect()
+    yield
+    # Shutdown
+    await app.state.cache.disconnect()
+
+app = FastAPI(
+    title="Service Name",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(health.router, tags=["health"])
+app.include_router(api.router, prefix="/api/v1", tags=["api"])
+```
+
+## Configuration with Pydantic Settings
+
+```python
+# config.py
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+class Settings(BaseSettings):
+    debug: bool = False
+    cors_origins: list[str] = ["*"]
+    database_url: str = "postgresql+asyncpg://user:pass@localhost/db"
+    redis_url: str = "redis://localhost:6379"
+    jwt_secret: str
+    jwt_algorithm: str = "HS256"
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = False
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+
+settings = get_settings()
+```
+
+## Pydantic Models (v2)
+
+```python
+from pydantic import BaseModel, Field
+from datetime import datetime
+from typing import Literal
+
+class MessageRequest(BaseModel):
+    content: str = Field(..., min_length=1, max_length=4000)
+    context: dict | None = None
+
+class MessageResponse(BaseModel):
+    message: str
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+class StreamChunk(BaseModel):
+    content: str
+    done: bool = False
+```
+
+## Dependency Injection
+
+```python
+# api/deps.py
+from typing import Annotated
+from fastapi import Depends, HTTPException, Header, status
+from jose import jwt, JWTError
+
+async def get_cache(request: Request) -> CacheService:
+    return request.app.state.cache
+
+async def verify_token(authorization: Annotated[str, Header()]) -> dict:
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+
+    token = authorization[7:]
+    try:
+        return jwt.decode(token, settings.jwt_secret, algorithms=[settings.jwt_algorithm])
+    except JWTError:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+
+async def get_tenant_id(token: Annotated[dict, Depends(verify_token)]) -> str:
+    tenant_id = token.get("tenant_id")
+    if not tenant_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+    return tenant_id
+
+# Type aliases
+TokenDep = Annotated[dict, Depends(verify_token)]
+TenantDep = Annotated[str, Depends(get_tenant_id)]
+CacheDep = Annotated[CacheService, Depends(get_cache)]
+```
+
+## Routes
+
+```python
+# api/routes/items.py
+from fastapi import APIRouter
+from fastapi.responses import StreamingResponse
+
+router = APIRouter()
+
+@router.post("", response_model=ItemResponse)
+async def create_item(
+    request: ItemRequest,
+    tenant_id: TenantDep,
+    service: ServiceDep,
+):
+    return await service.create(request, tenant_id)
+
+@router.post("/stream")
+async def stream_response(request: Request, service: ServiceDep):
+    async def generate():
+        async for chunk in service.stream():
+            yield f"data: {chunk.model_dump_json()}\n\n"
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(generate(), media_type="text/event-stream")
+```
+
+## Async Service Pattern
+
+```python
+class ItemService:
+    def __init__(self, cache: CacheService):
+        self.cache = cache
+
+    async def create(self, request: ItemRequest, tenant_id: str) -> ItemResponse:
+        # Business logic here
+        result = await self._process(request)
+        await self.cache.set(f"item:{result.id}", result.model_dump())
+        return result
+
+    async def stream(self) -> AsyncIterator[StreamChunk]:
+        async for chunk in self._generate():
+            yield StreamChunk(content=chunk)
+        yield StreamChunk(content="", done=True)
+```
+
+## Redis Cache Service
+
+```python
+import redis.asyncio as redis
+import json
+
+class CacheService:
+    def __init__(self):
+        self.redis: redis.Redis | None = None
+
+    async def connect(self):
+        self.redis = await redis.from_url(settings.redis_url)
+
+    async def disconnect(self):
+        if self.redis:
+            await self.redis.close()
+
+    async def get(self, key: str) -> Any | None:
+        data = await self.redis.get(key)
+        return json.loads(data) if data else None
+
+    async def set(self, key: str, value: Any, ttl: int = 3600):
+        await self.redis.setex(key, ttl, json.dumps(value))
+```
+
+## Custom Exceptions
+
+```python
+from fastapi import HTTPException, status
+
+class ServiceException(HTTPException):
+    def __init__(self, detail: str):
+        super().__init__(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=detail)
+
+class RateLimitException(HTTPException):
+    def __init__(self):
+        super().__init__(status_code=status.HTTP_429_TOO_MANY_REQUESTS, detail="Rate limit exceeded")
+```
+
+## Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+from app.main import app
+
+@pytest.fixture
+async def client():
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_create_item(client: AsyncClient, auth_token: str):
+    response = await client.post(
+        "/api/v1/items",
+        json={"content": "test"},
+        headers={"Authorization": f"Bearer {auth_token}"},
+    )
+    assert response.status_code == 200
+    assert "message" in response.json()
+```
+
+## Dockerfile
+
+```dockerfile
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY src/ ./src/
+ENV PYTHONPATH=/app/src
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Best Practices
+
+1. **Use Pydantic v2**: `BaseModel`, `Field`, `model_dump()`, `model_validate_json()`
+2. **Async everywhere**: Never block the event loop with sync operations
+3. **Dependency injection**: Use `Annotated[Type, Depends(fn)]` pattern
+4. **Type hints**: Full typing for all functions and returns
+5. **Lifespan context**: Manage startup/shutdown with `asynccontextmanager`
+
+## Related Skills
+
+- `jwt-auth`: Authentication patterns
+- `redis-cache`: Response caching
+- `langchain`: LLM integration
+- `opentelemetry`: Observability
+- `docker-containers`: Deployment