maestro-bundle 1.3.1 → 1.5.0

package/templates/bundle-data-pipeline/skills/rag-pipeline/references/embedding-models.md

@@ -0,0 +1,49 @@
+# Embedding Models Comparison
+
+## OpenAI Models
+
+| Model | Dimensions | Max Tokens | Best For |
+|---|---|---|---|
+| text-embedding-3-large | 3072 (or custom) | 8191 | Highest quality, production |
+| text-embedding-3-small | 1536 | 8191 | Cost-effective, good quality |
+| text-embedding-ada-002 | 1536 | 8191 | Legacy, still widely used |
+
+## Usage with LangChain
+```python
+from langchain_openai import OpenAIEmbeddings
+
+# Default (text-embedding-3-large with reduced dimensions)
+embeddings = OpenAIEmbeddings(model="text-embedding-3-large", dimensions=1536)
+
+# Full dimensions for maximum quality
+embeddings = OpenAIEmbeddings(model="text-embedding-3-large", dimensions=3072)
+
+# Cost-effective option
+embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+```
+
+## Open Source Alternatives
+```python
+from langchain_community.embeddings import HuggingFaceEmbeddings
+
+# All-MiniLM (fast, lightweight)
+embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
+
+# BGE (high quality, multilingual)
+embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-large-en-v1.5")
+```
+
+## Dimensionality and pgvector
+When creating the pgvector extension and table:
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Match dimensions to your embedding model
+CREATE TABLE embeddings (
+    id SERIAL PRIMARY KEY,
+    content TEXT,
+    embedding vector(1536)  -- adjust to match model dimensions
+);
+
+CREATE INDEX ON embeddings USING ivfflat (embedding vector_cosine_ops);
+```

package/templates/bundle-frontend-spa/AGENTS.md

@@ -14,6 +14,12 @@ Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qual
 
 Nunca pular direto para código. Spec primeiro, código depois.
 
+## Product Requirements Document
+
+O arquivo `PRD.md` na raiz do projeto contém os requisitos do produto definidos pelo analista/dev. Consulte-o para entender O QUE construir, as user stories, critérios de aceite, modelo de dados e API specification. Este AGENTS.md define COMO o agente deve trabalhar; o PRD define O QUE deve ser construído.
+
+- `PRD.md` — Requisitos do produto, user stories, API spec, modelo de dados
+
 ## References
 
 Documentos de referência que o agente deve consultar quando necessário:

package/templates/bundle-frontend-spa/PRD_TEMPLATE.md

@@ -0,0 +1,161 @@
+# Product Requirements Document (PRD)
+
+> Este documento define os requisitos do produto. Deve ser preenchido pelo analista de requisitos e/ou pelo dev antes de iniciar o desenvolvimento. O agente AI usa este documento como contexto para entender O QUE construir.
+
+## 1. Resumo Executivo
+
+<!-- Descreva em 2-3 frases o que é o produto e qual problema resolve -->
+
+## 2. Usuários Alvo
+
+<!-- Quem vai usar o sistema? Descreva as personas -->
+
+### Persona 1: [Nome]
+- **Perfil:**
+- **Objetivos:**
+- **Dores:**
+
+## 3. Escopo do MVP
+
+### Incluído no MVP
+- [ ] Feature 1
+- [ ] Feature 2
+- [ ] Feature 3
+
+### Fora do MVP (futuro)
+- [ ] Feature futura 1
+- [ ] Feature futura 2
+
+## 4. User Stories
+
+### US01: [Título]
+**Como** [persona], **quero** [ação], **para** [benefício].
+
+**Critérios de aceite:**
+- [ ] CA1:
+- [ ] CA2:
+
+### US02: [Título]
+**Como** [persona], **quero** [ação], **para** [benefício].
+
+**Critérios de aceite:**
+- [ ] CA1:
+- [ ] CA2:
+
+## 5. Arquitetura de Alto Nível
+
+<!-- Diagrama em Mermaid ou ASCII mostrando os componentes principais -->
+
+```mermaid
+graph LR
+    A[Frontend] --> B[API]
+    B --> C[Database]
+```
+
+### Estrutura de Diretórios
+
+```
+project/
+├── src/
+├── tests/
+└── ...
+```
+
+## 6. Features Detalhadas
+
+### Feature 1: [Nome]
+- **Descrição:**
+- **Regras de negócio:**
+  -
+- **Inputs:**
+- **Outputs:**
+- **Edge cases:**
+  -
+
+### Feature 2: [Nome]
+- **Descrição:**
+- **Regras de negócio:**
+  -
+
+## 7. Stack Tecnológica
+
+| Componente | Tecnologia | Justificativa |
+|---|---|---|
+| Backend | | |
+| Frontend | | |
+| Banco de dados | | |
+| Cache | | |
+| Deploy | | |
+
+## 8. API Specification
+
+### Endpoints
+
+#### `GET /api/v1/resource`
+- **Descrição:**
+- **Response:** `200 OK`
+```json
+{
+  "items": [],
+  "total": 0,
+  "page": 1,
+  "size": 20
+}
+```
+
+#### `POST /api/v1/resource`
+- **Descrição:**
+- **Body:**
+```json
+{
+  "field": "value"
+}
+```
+- **Response:** `201 Created`
+
+## 9. Modelo de Dados
+
+```sql
+CREATE TABLE example (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(100) NOT NULL,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+## 10. Requisitos Não-Funcionais
+
+| Requisito | Alvo | Prioridade |
+|---|---|---|
+| Performance | Response time < 500ms | Alta |
+| Disponibilidade | 99.9% uptime | Média |
+| Segurança | OWASP Top 10 | Alta |
+| Escalabilidade | Até X usuários simultâneos | Média |
+
+## 11. Fases de Implementação
+
+### Fase 1: Foundation
+- [ ] Setup do projeto
+- [ ] Modelo de dados
+- [ ] Endpoints básicos
+
+### Fase 2: Core Features
+- [ ] Feature 1 completa
+- [ ] Feature 2 completa
+
+### Fase 3: Polish
+- [ ] Testes E2E
+- [ ] Performance
+- [ ] Documentação
+
+## 12. Riscos e Mitigações
+
+| Risco | Impacto | Probabilidade | Mitigação |
+|---|---|---|---|
+| | | | |
+
+## 13. Critérios de Sucesso
+
+- [ ] Critério 1
+- [ ] Critério 2
+- [ ] Critério 3

package/templates/bundle-frontend-spa/skills/authentication/SKILL.md

@@ -1,17 +1,43 @@
 ---
 name: authentication
-description: Implementar autenticação JWT com login, refresh token e proteção de rotas no frontend e backend. Use quando precisar implementar login, auth, JWT, ou proteção de endpoints.
+description: Implement JWT authentication with login, refresh tokens, route protection, and Axios interceptors for both frontend and backend. Use when you need to add login, JWT auth, protected routes, or token refresh to an application.
+version: 1.0.0
+author: Maestro
 ---
 
 # Authentication
 
-## Backend — JWT com FastAPI
+Implement complete JWT authentication flow covering backend token generation, frontend auth state, Axios interceptors, and protected routes.
 
+## When to Use
+- User needs to implement login/logout functionality
+- User wants to protect routes requiring authentication
+- User needs JWT token generation and validation (backend)
+- User wants to add automatic token refresh
+- User needs to set up Axios interceptors for auth headers
+
+## Available Operations
+1. Create JWT token generation and validation (FastAPI backend)
+2. Build login/logout flow with Zustand auth store
+3. Set up Axios interceptors for automatic Bearer token headers
+4. Implement protected route wrappers
+5. Add refresh token rotation
+
+## Multi-Step Workflow
+
+### Step 1: Install Backend Dependencies
+```bash
+pip install fastapi python-jose[cryptography] passlib[bcrypt] python-multipart
+```
+
+### Step 2: Create JWT Token Utilities (Backend)
 ```python
+# src/auth/jwt.py
+import os
+from datetime import datetime, timedelta
+from jose import jwt, JWTError
 from fastapi import Depends, HTTPException, status
 from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
-from jose import jwt, JWTError
-from datetime import datetime, timedelta
 
 security = HTTPBearer()
 SECRET_KEY = os.environ["JWT_SECRET"]
@@ -23,7 +49,7 @@ def create_access_token(user_id: str) -> str:
     payload = {
         "sub": user_id,
         "exp": datetime.utcnow() + ACCESS_TOKEN_EXPIRE,
-        "type": "access"
+        "type": "access",
     }
     return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
 
@@ -31,11 +57,13 @@ def create_refresh_token(user_id: str) -> str:
     payload = {
         "sub": user_id,
         "exp": datetime.utcnow() + REFRESH_TOKEN_EXPIRE,
-        "type": "refresh"
+        "type": "refresh",
     }
     return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
 
-async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)) -> User:
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+) -> User:
     try:
         payload = jwt.decode(credentials.credentials, SECRET_KEY, algorithms=[ALGORITHM])
         if payload.get("type") != "access":
@@ -46,22 +74,68 @@ async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(s
         return user
     except JWTError:
         raise HTTPException(status_code=401, detail="Invalid token")
+```
+
+### Step 3: Create Auth Endpoints (Backend)
+```python
+# src/auth/routes.py
+from fastapi import APIRouter, HTTPException
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+@router.post("/login")
+async def login(data: LoginRequest):
+    user = await user_repo.find_by_email(data.email)
+    if not user or not verify_password(data.password, user.hashed_password):
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+    return {
+        "access_token": create_access_token(str(user.id)),
+        "refresh_token": create_refresh_token(str(user.id)),
+        "user": UserResponse.from_entity(user),
+    }
+
+@router.post("/refresh")
+async def refresh(data: RefreshRequest):
+    try:
+        payload = jwt.decode(data.refresh_token, SECRET_KEY, algorithms=[ALGORITHM])
+        if payload.get("type") != "refresh":
+            raise HTTPException(status_code=401, detail="Invalid token type")
+        return {"access_token": create_access_token(payload["sub"])}
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
 
-# Endpoint protegido
 @router.get("/me")
 async def get_me(user: User = Depends(get_current_user)):
     return UserResponse.from_entity(user)
 ```
 
-## Frontend — Auth Context
+Test the backend:
+```bash
+# Start the API server
+uvicorn src.main:app --reload --port 8000
 
+# Test login
+curl -X POST http://localhost:8000/auth/login -H "Content-Type: application/json" -d '{"email": "admin@example.com", "password": "admin123"}'
+```
+
+### Step 4: Install Frontend Dependencies
+```bash
+npm install axios zustand
+```
+
+### Step 5: Create Auth Store (Frontend)
 ```tsx
+// src/stores/useAuthStore.ts
+import { create } from 'zustand';
+import { authApi } from '@/services/authApi';
+
 interface AuthState {
   token: string | null;
   user: User | null;
+  isAuthenticated: boolean;
   login: (email: string, password: string) => Promise<void>;
   logout: () => void;
-  isAuthenticated: boolean;
+  setToken: (token: string) => void;
 }
 
 export const useAuthStore = create<AuthState>((set) => ({
@@ -70,21 +144,130 @@ export const useAuthStore = create<AuthState>((set) => ({
   isAuthenticated: !!localStorage.getItem('token'),
 
   login: async (email, password) => {
-    const { access_token, user } = await authApi.login(email, password);
+    const { access_token, refresh_token, user } = await authApi.login(email, password);
     localStorage.setItem('token', access_token);
+    localStorage.setItem('refresh_token', refresh_token);
     set({ token: access_token, user, isAuthenticated: true });
   },
 
   logout: () => {
     localStorage.removeItem('token');
+    localStorage.removeItem('refresh_token');
     set({ token: null, user: null, isAuthenticated: false });
   },
+
+  setToken: (token) => {
+    localStorage.setItem('token', token);
+    set({ token });
+  },
 }));
+```
+
+### Step 6: Set Up Axios Interceptors
+```tsx
+// src/lib/api.ts
+import axios from 'axios';
+import { useAuthStore } from '@/stores/useAuthStore';
 
-// Axios interceptor
+export const api = axios.create({
+  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:8000/api/v1',
+  timeout: 10000,
+});
+
+// Add auth header to every request
 api.interceptors.request.use((config) => {
   const token = localStorage.getItem('token');
-  if (token) config.headers.Authorization = `Bearer ${token}`;
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
   return config;
 });
+
+// Handle 401 responses: try refresh, then logout
+api.interceptors.response.use(
+  (response) => response.data,
+  async (error) => {
+    if (error.response?.status === 401) {
+      const refreshToken = localStorage.getItem('refresh_token');
+      if (refreshToken && !error.config._retry) {
+        error.config._retry = true;
+        try {
+          const { access_token } = await authApi.refresh(refreshToken);
+          useAuthStore.getState().setToken(access_token);
+          error.config.headers.Authorization = `Bearer ${access_token}`;
+          return api(error.config);
+        } catch {
+          useAuthStore.getState().logout();
+          window.location.href = '/login';
+        }
+      } else {
+        useAuthStore.getState().logout();
+        window.location.href = '/login';
+      }
+    }
+    return Promise.reject(error.response?.data || error);
+  }
+);
+```
+
+### Step 7: Create Protected Route Wrapper
+```tsx
+// src/components/ProtectedRoute.tsx
+import { Navigate } from 'react-router-dom';
+import { useAuthStore } from '@/stores/useAuthStore';
+
+export function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const isAuthenticated = useAuthStore((s) => s.isAuthenticated);
+
+  if (!isAuthenticated) {
+    return <Navigate to="/login" replace />;
+  }
+
+  return <>{children}</>;
+}
+
+// Usage in router:
+// <Route path="/dashboard" element={<ProtectedRoute><Dashboard /></ProtectedRoute>} />
 ```
+
+### Step 8: Verify the Auth Flow
+```bash
+npm run dev
+# 1. Navigate to /login
+# 2. Enter credentials and submit
+# 3. Verify redirect to /dashboard
+# 4. Verify protected routes redirect to /login when not authenticated
+# 5. Verify token is in localStorage
+# 6. Verify API calls include Authorization header (check Network tab)
+```
+
+## Resources
+- `references/jwt-security.md` - JWT security best practices and common vulnerabilities
+
+## Examples
+### Example 1: Add Login to an Existing App
+User asks: "Add authentication to our React app with a login page"
+Response approach:
+1. Create backend auth endpoints (login, refresh, me)
+2. Create useAuthStore with Zustand
+3. Set up Axios interceptors for token management
+4. Create LoginPage component with form
+5. Wrap routes in ProtectedRoute
+6. Test the full flow end-to-end
+
+### Example 2: Fix Token Expiry Issues
+User asks: "Users keep getting logged out, how do I add token refresh?"
+Response approach:
+1. Add refresh token endpoint to backend
+2. Store refresh token in localStorage alongside access token
+3. Add 401 interceptor that tries refresh before logging out
+4. Set retry flag to prevent infinite refresh loops
+5. Test by setting short access token expiry and verifying refresh works
+
+## Notes
+- Never store tokens in cookies without httpOnly + secure + sameSite flags
+- Set a reasonable access token expiry (1 hour) and longer refresh token (7 days)
+- Always validate token type ("access" vs "refresh") server-side
+- Use environment variables for JWT_SECRET, never hardcode
+- Implement rate limiting on login endpoints to prevent brute force
+- Clear all stored tokens on logout

package/templates/bundle-frontend-spa/skills/authentication/references/jwt-security.md

@@ -0,0 +1,41 @@
+# JWT Security Best Practices
+
+## Token Storage
+| Method | Security | XSS Risk | CSRF Risk |
+|---|---|---|---|
+| localStorage | Low | High | None |
+| httpOnly Cookie | High | None | Medium |
+| In-memory (variable) | Highest | None | None |
+
+Recommendation: Use httpOnly cookies for production, localStorage for development/SPAs.
+
+## Token Expiry
+| Token Type | Recommended Expiry |
+|---|---|
+| Access Token | 15 min - 1 hour |
+| Refresh Token | 7 - 30 days |
+
+## Security Checklist
+- [ ] Use strong secret key (256+ bits): `openssl rand -hex 32`
+- [ ] Set algorithm explicitly (HS256 or RS256), never "none"
+- [ ] Validate token type (access vs refresh) on every endpoint
+- [ ] Implement refresh token rotation (new refresh token on each use)
+- [ ] Rate limit login endpoint (5 attempts per minute)
+- [ ] Log failed login attempts
+- [ ] Clear all tokens on logout (both client and server)
+- [ ] Use HTTPS in production
+
+## Common Vulnerabilities
+1. **Algorithm confusion**: Always specify algorithm in `jwt.decode()`, never accept from token
+2. **Missing expiry check**: Always include `exp` claim
+3. **Token reuse after logout**: Maintain a blocklist or use short-lived tokens
+4. **Refresh without rotation**: Rotate refresh tokens to limit damage from stolen tokens
+
+## Generating a Secure Secret
+```bash
+# Generate a 256-bit hex secret
+openssl rand -hex 32
+
+# Or with Python
+python -c "import secrets; print(secrets.token_hex(32))"
+```