@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/ide/cursor/.cursor/rules/skill-fastapi-api.mdc

@@ -0,0 +1,352 @@
+---
+description: Padrões DARE para APIs REST em Python + FastAPI + Pydantic v2 + SQLAlchemy 2.0 async + alembic. Routers, dependency injection, schemas Pydantic, OAuth2+JWT, slowapi rate limit, pytest+httpx, OpenAPI auto-gerado.
+globs: **/*.py,pyproject.toml,requirements.txt,alembic.ini,alembic/**/*.py
+alwaysApply: false
+---
+
+# Skill: FastAPI API DARE
+
+Você é um desenvolvedor sênior Python especialista em APIs REST com FastAPI. Esta skill garante código **assíncrono, fortemente tipado (Pydantic v2), com OpenAPI auto-gerado, auth/autz robustos**, seguindo Layered Design DARE.
+
+## Stack canônica
+
+- **Python 3.11+** com type hints obrigatórios
+- **FastAPI 0.115+** com async/await
+- **Pydantic v2** para schemas
+- **SQLAlchemy 2.0** async + **asyncpg** (PostgreSQL)
+- **alembic** para migrations
+- **passlib + argon2** para hash de senhas
+- **python-jose** ou **PyJWT** para JWT
+- **slowapi** para rate limiting
+- **pytest + pytest-asyncio + httpx**
+- **ruff** (lint + format) + **mypy**
+
+---
+
+## Estrutura de pastas
+
+```
+app/
+├── main.py                       ← FastAPI app + middlewares
+├── core/
+│   ├── config.py                 ← pydantic-settings
+│   └── security.py               ← hash, JWT
+├── api/
+│   ├── deps.py                   ← Depends() comuns
+│   └── v1/
+│       ├── users.py              ← Handler (router)
+│       └── auth.py
+├── services/                     ← Service layer
+├── repositories/                 ← Repository layer
+├── models/                       ← SQLAlchemy ORM
+├── schemas/                      ← Pydantic DTOs
+└── tests/
+```
+
+---
+
+## Routers (Handler)
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, status
+from app.api.deps import get_current_user
+from app.schemas.user import UserCreate, UserOut
+from app.services.register_user import RegisterUser, UserAlreadyExistsError
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    payload: UserCreate,
+    service: RegisterUser = Depends(),
+    _current: User = Depends(get_current_user),
+):
+    try:
+        return await service.execute(payload)
+    except UserAlreadyExistsError:
+        raise HTTPException(status_code=409, detail="User already exists")
+```
+
+Regras:
+- Apenas: valida via Pydantic → chama Service → retorna response_model
+- NUNCA: SQLAlchemy direto, lógica de negócio, validação manual
+
+---
+
+## Schemas (Pydantic v2)
+
+```python
+from pydantic import BaseModel, EmailStr, Field
+from datetime import datetime
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=255)
+    password: str = Field(min_length=12)
+
+class UserOut(BaseModel):
+    id: int
+    email: EmailStr
+    name: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}   # Pydantic v2 substitui orm_mode
+```
+
+---
+
+## Services
+
+```python
+class UserAlreadyExistsError(Exception): ...
+
+class RegisterUser:
+    def __init__(self, repo: UsersRepository = Depends()):
+        self.repo = repo
+
+    async def execute(self, payload: UserCreate) -> User:
+        if await self.repo.exists_by_email(payload.email):
+            raise UserAlreadyExistsError()
+        return await self.repo.create(
+            email=payload.email,
+            name=payload.name,
+            password_hash=hash_password(payload.password),
+        )
+```
+
+---
+
+## Repositories (SQLAlchemy 2.0 async)
+
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import Depends
+from app.api.deps import get_db
+
+class UsersRepository:
+    def __init__(self, db: AsyncSession = Depends(get_db)):
+        self.db = db
+
+    async def exists_by_email(self, email: str) -> bool:
+        result = await self.db.execute(select(User.id).where(User.email == email))
+        return result.scalar_one_or_none() is not None
+
+    async def create(self, *, email: str, name: str, password_hash: str) -> User:
+        user = User(email=email, name=name, password_hash=password_hash)
+        self.db.add(user)
+        await self.db.commit()
+        await self.db.refresh(user)
+        return user
+```
+
+---
+
+## Models (SQLAlchemy 2.0)
+
+```python
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from datetime import datetime
+
+class Base(DeclarativeBase): ...
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    name: Mapped[str]
+    password_hash: Mapped[str]
+    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)
+```
+
+---
+
+## Auth (OAuth2 + JWT)
+
+```python
+# app/core/security.py
+from passlib.hash import argon2
+from datetime import datetime, timedelta
+from jose import jwt
+from app.core.config import settings
+
+def hash_password(p: str) -> str: return argon2.hash(p)
+def verify_password(p: str, h: str) -> bool: return argon2.verify(p, h)
+
+def create_access_token(sub: str) -> str:
+    expire = datetime.utcnow() + timedelta(minutes=15)
+    return jwt.encode({"sub": sub, "exp": expire}, settings.JWT_SECRET, algorithm="HS256")
+```
+
+```python
+# app/api/deps.py
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/v1/auth/login")
+
+async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    ...
+```
+
+---
+
+## Rate limiting (slowapi)
+
+```python
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+app.state.limiter = limiter
+app.add_middleware(SlowAPIMiddleware)
+
+@router.post("/login")
+@limiter.limit("5/15minute")
+async def login(request: Request, ...):
+    ...
+```
+
+---
+
+## OpenAPI
+
+FastAPI auto-gera em `/openapi.json`. Customize:
+
+```python
+app = FastAPI(
+    title="Projeto API",
+    version="1.0",
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+```
+
+---
+
+## Settings (pydantic-settings)
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    DATABASE_URL: str
+    JWT_SECRET: str
+    JWT_EXPIRE_MINUTES: int = 15
+    model_config = SettingsConfigDict(env_file=".env")
+
+settings = Settings()
+```
+
+---
+
+## Testes (pytest + httpx)
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient, admin_token: str):
+    response = await client.post(
+        "/v1/users",
+        json={"email": "jane@example.com", "name": "Jane", "password": "longsecret123"},
+        headers={"Authorization": f"Bearer {admin_token}"},
+    )
+    assert response.status_code == 201
+    assert response.json()["email"] == "jane@example.com"
+
+@pytest.mark.asyncio
+async def test_duplicate_email(client, admin_token):
+    await client.post("/v1/users", json={...}, headers={...})
+    response = await client.post("/v1/users", json={...}, headers={...})
+    assert response.status_code == 409
+```
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | SQLAlchemy direto no router | Repository injetado via Depends |
+| AP-02 | Validação manual no router | Pydantic schema |
+| AP-03 | Lógica no router | Service |
+| AP-04 | `return user` (ORM) sem response_model | `response_model=UserOut` |
+| AP-05 | Secret hardcoded | pydantic-settings + .env |
+| AP-06 | Login sem rate limit | `@limiter.limit("5/15minute")` |
+| AP-07 | Senha em response | response_model sem password |
+| AP-08 | Sem `from_attributes=True` | adicionar no model_config |
+| AP-09 | `db.execute` sem await | sempre `await db.execute(...)` |
+| AP-10 | Mistura sync/async no router | tudo `async def` |
+
+---
+
+## Segurança
+
+- Senhas: `argon2.hash()` (passlib)
+- JWT: HS256 com `JWT_SECRET ≥ 32 bytes`, ou RS256 com par de chaves
+- Headers: middleware com HSTS, X-Frame-Options, CSP
+- CORS específico, nunca `*`
+- Rate limit em login + APIs públicas
+- Refresh token com rotação no DB
+
+---
+
+## CI
+
+```bash
+ruff check .
+ruff format --check .
+mypy app
+pytest --cov=app --cov-fail-under=80
+pip-audit
+alembic upgrade head --sql > /dev/null
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Endpoints REST com tags
+- Schemas Pydantic de input/output
+- Auth strategy
+
+### Blueprint
+- Estrutura de pastas
+- SQLAlchemy models preliminares
+- Roteamento `app.include_router(...)`
+
+### Tasks
+- Por feature: 4 tasks (Model, Schema, Repository, Service, Router)
+- Task de configuração slowapi + auth + OpenAPI custom
+
+### Execute
+- Ralph Loop:
+  ```bash
+  ruff check . && mypy app && pytest && pip-audit
+  ```
+
+---
+
+## Checklist final
+
+- [ ] Python 3.11+, ruff configurado
+- [ ] Pydantic v2 com `model_config = {"from_attributes": True}` quando ORM
+- [ ] SQLAlchemy 2.0 async com `Mapped[...]`
+- [ ] Todos routers usam `response_model=`
+- [ ] Services injetáveis via `Depends()`
+- [ ] Repositories encapsulam SQLAlchemy
+- [ ] `slowapi` em login + APIs públicas
+- [ ] Settings via pydantic-settings + .env
+- [ ] `mypy --strict` passa
+- [ ] Cobertura ≥ 80%
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.

package/templates/ide/cursor/.cursor/rules/skill-frontend-design.mdc

@@ -0,0 +1,244 @@
+---
+description: Arquitetura frontend DARE para projetos React e Vue. Detecta god components (>300 linhas), fetch inline em JSX/template, garante error boundaries, loading states e bundle size monitorado.
+globs: src/**/*.tsx,src/**/*.ts,src/**/*.jsx,src/**/*.js,src/**/*.vue,vite.config.ts,vite.config.js,webpack.config.js
+alwaysApply: false
+---
+
+# Skill: Frontend Design DARE
+
+Você é um arquiteto frontend especialista em React e Vue. Esta skill enforce arquitetura limpa em camadas no frontend, com **componentes pequenos, sem fetch inline, error boundaries explícitos e bundle monitorado**.
+
+## Arquitetura recomendada
+
+### React
+
+```
+┌──────────────────────────────────────────────────┐
+│  Page  (rota, layout)                            │  ← top-level
+└──────────────────────────────────────────────────┘
+              ↓ usa
+┌──────────────────────────────────────────────────┐
+│  Container  (lógica + estado)                    │  ← orquestrador
+└──────────────────────────────────────────────────┘
+              ↓ injeta props
+┌──────────────────────────────────────────────────┐
+│  Presentational  (puro, recebe props)            │  ← visual
+└──────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────┐
+│  Hook de dados (useUser, useOrders…)             │  ← fetch + cache
+└──────────────────────────────────────────────────┘
+```
+
+### Vue (Composition API)
+
+```
+Page.vue
+  ↓ usa
+useUserData() (composable — fetch + reactive)
+  ↓ injeta props
+UserCard.vue (presentational)
+```
+
+---
+
+## As 4 regras
+
+### 1. Componente < 300 linhas (M-01)
+
+Se um arquivo `.tsx`/`.vue` passar de 300 linhas, quebrar em:
+- Sub-componentes lógicos
+- Hook/composable separado para estado
+- Helper para transformações de dados
+
+### 2. Zero `fetch()` direto em JSX/template (M-02)
+
+```tsx
+// ❌ Errado
+function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers);
+  }, []);
+  return <ul>{users.map(...)}</ul>;
+}
+
+// ✅ Certo — hook isolado e testável
+function UserList() {
+  const { data, isLoading, error } = useUsers();
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage error={error} />;
+  return <ul>{data.map(...)}</ul>;
+}
+
+function useUsers() {
+  return useQuery({ queryKey: ['users'], queryFn: () => api.users.list() });
+}
+```
+
+### 3. Error Boundary em cada Page (M-03)
+
+```tsx
+// React
+class ErrorBoundary extends React.Component {
+  state = { error: null };
+  static getDerivedStateFromError(error: Error) { return { error }; }
+  componentDidCatch(error: Error, info: ErrorInfo) { logError(error, info); }
+  render() {
+    if (this.state.error) return this.props.fallback;
+    return this.props.children;
+  }
+}
+
+// Wrap cada Page
+<ErrorBoundary fallback={<ErrorPage />}>
+  <UsersPage />
+</ErrorBoundary>
+```
+
+```vue
+<!-- Vue -->
+<script setup>
+import { onErrorCaptured } from 'vue';
+onErrorCaptured((err, instance, info) => {
+  logError(err, info);
+  return false; // stops propagation
+});
+</script>
+```
+
+### 4. Bundle size monitorado (M-04)
+
+```typescript
+// vite.config.ts
+import { visualizer } from 'rollup-plugin-visualizer';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    visualizer({ open: false, gzipSize: true, filename: 'dist/stats.html' }),
+  ],
+  build: {
+    chunkSizeWarningLimit: 300, // KB
+  },
+});
+```
+
+---
+
+## Métricas (verificáveis em CI)
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% de componentes < 300 linhas | `wc -l` por arquivo, fail se >300 |
+| M-02 | 0 `fetch()` direto em JSX/template | grep AST nos componentes |
+| M-03 | 100% de páginas com error boundary | grep por `ErrorBoundary` ou `onErrorCaptured` |
+| M-04 | Bundle config presente | `test -f vite.config.ts` + check de `chunkSizeWarningLimit` |
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Sinal | Correção |
+|---|---|---|---|
+| AP-01 | God component | >300 linhas | Quebrar em sub-componentes + hooks |
+| AP-02 | Fetch em JSX | `useEffect(() => fetch())` | Hook customizado |
+| AP-03 | Booleanos isLoading espalhados | `isLoading`, `isError`, `isSubmitting` separados | Discriminated union (`state: 'idle' \| 'loading' \| 'success' \| 'error'`) |
+| AP-04 | Sem error boundary | erro derruba app | Wrap em `<ErrorBoundary>` |
+| AP-05 | Estilo inline pesado | `style={{...30 props}}` | CSS Module / Tailwind / styled |
+| AP-06 | Props drilling profundo | passa prop 5+ níveis | Context API ou Zustand/Pinia |
+
+---
+
+## Stack recomendada
+
+| Camada | React | Vue |
+|---|---|---|
+| Roteamento | React Router 7 / Next 14 / TanStack Router | Vue Router / Nuxt 3 |
+| Estado server | TanStack Query | TanStack Vue Query / Pinia Colada |
+| Estado client | Zustand / Jotai | Pinia |
+| Forms | React Hook Form / TanStack Form | VeeValidate / TanStack Form |
+| Styling | Tailwind + CSS Modules | Tailwind + SCSS |
+| Testes | Vitest + Testing Library | Vitest + Testing Library |
+| E2E | Playwright | Playwright |
+| Bundler | Vite | Vite |
+
+---
+
+## Scaffold de página DARE-compliant
+
+```tsx
+// src/pages/UsersPage.tsx
+import { ErrorBoundary } from '@/components/ErrorBoundary';
+import { UsersContainer } from '@/containers/UsersContainer';
+
+export function UsersPage() {
+  return (
+    <ErrorBoundary fallback={<ErrorPage />}>
+      <UsersContainer />
+    </ErrorBoundary>
+  );
+}
+
+// src/containers/UsersContainer.tsx
+import { useUsers } from '@/hooks/useUsers';
+import { UserList } from '@/components/UserList';
+
+export function UsersContainer() {
+  const { data, isLoading, error } = useUsers();
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage error={error} />;
+  return <UserList users={data} />;
+}
+
+// src/components/UserList.tsx — presentational puro
+export function UserList({ users }: { users: User[] }) {
+  return <ul>{users.map(u => <UserItem key={u.id} user={u} />)}</ul>;
+}
+
+// src/hooks/useUsers.ts
+export function useUsers() {
+  return useQuery({
+    queryKey: ['users'],
+    queryFn: () => api.users.list(),
+    staleTime: 60_000,
+  });
+}
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Listar páginas/rotas no DESIGN.md
+- Definir estados de cada rota (idle/loading/success/error)
+
+### Blueprint
+- Estrutura de pastas (`src/pages/`, `src/containers/`, `src/components/`, `src/hooks/`)
+- Stack escolhida (React Query vs SWR, Zustand vs Redux, etc.)
+
+### Tasks
+- 1 task por página com 3 sub-tasks: Page, Container, Hook
+- Task de configuração de Error Boundary global
+- Task de configuração de bundle visualizer
+
+### Execute
+- Ralph Loop falha se: arquivo >300 linhas, `fetch()` em componente, página sem error boundary
+
+---
+
+## Checklist final
+
+- [ ] Pastas `src/pages/`, `src/containers/`, `src/components/`, `src/hooks/`
+- [ ] Todos os componentes < 300 linhas
+- [ ] Zero `fetch()` direto em componente
+- [ ] Cada Page tem `<ErrorBoundary>` ou `onErrorCaptured`
+- [ ] `chunkSizeWarningLimit` configurado no bundler
+- [ ] TanStack Query (ou equivalente) configurado
+- [ ] Testes com Testing Library para Presentational
+- [ ] Testes com mock do Hook para Container
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.