devsquad 1.0.0 → 1.1.0

package/templates/.claude/skills/nestjs/api-contracts.md

@@ -0,0 +1,221 @@
+# NestJS — Contratos de API (Formato padrão)
+
+## Formato padrão de resposta
+
+Todas as respostas da API seguem este contrato. Isso garante que o frontend possa tratar respostas de forma consistente.
+
+### Sucesso
+
+```typescript
+// Resposta de sucesso — item único
+{
+  "data": { "id": "uuid", "name": "João", "email": "joao@email.com" },
+  "meta": null
+}
+
+// Resposta de sucesso — lista paginada
+{
+  "data": [{ "id": "uuid", "name": "João" }],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "perPage": 20,
+    "totalPages": 5
+  }
+}
+
+// Resposta de criação (201)
+{
+  "data": { "id": "uuid-novo" }
+}
+
+// Resposta sem conteúdo (204) — sem body
+```
+
+### Erro
+
+```typescript
+// Erro de validação (400)
+{
+  "statusCode": 400,
+  "error": "Bad Request",
+  "message": ["email must be an email", "password is too weak"]
+}
+
+// Erro de autenticação (401)
+{
+  "statusCode": 401,
+  "error": "Unauthorized",
+  "message": "Credenciais inválidas"
+}
+
+// Erro de permissão (403)
+{
+  "statusCode": 403,
+  "error": "Forbidden",
+  "message": "Sem permissão para esta ação"
+}
+
+// Não encontrado (404)
+{
+  "statusCode": 404,
+  "error": "Not Found",
+  "message": "Usuário não encontrado"
+}
+
+// Conflito (409)
+{
+  "statusCode": 409,
+  "error": "Conflict",
+  "message": "E-mail já cadastrado"
+}
+```
+
+## Implementação — Response Interceptor
+
+```typescript
+// src/common/interceptors/response.interceptor.ts
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+export interface ApiResponse<T> {
+  data: T;
+  meta: PaginationMeta | null;
+}
+
+export interface PaginationMeta {
+  total: number;
+  page: number;
+  perPage: number;
+  totalPages: number;
+}
+
+@Injectable()
+export class ResponseInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<ApiResponse<T>> {
+    return next.handle().pipe(
+      map((value) => {
+        // Se já tem formato { data, meta } — retorna como está
+        if (value && 'data' in value) return value;
+        // Caso contrário, envolve em { data, meta: null }
+        return { data: value, meta: null };
+      }),
+    );
+  }
+}
+```
+
+```typescript
+// src/main.ts — registrar globalmente
+app.useGlobalInterceptors(new ResponseInterceptor());
+```
+
+## Implementação — Paginação
+
+```typescript
+// src/common/dto/pagination.dto.ts
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, Max, Min } from 'class-validator';
+
+export class PaginationDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  perPage: number = 20;
+
+  get skip(): number {
+    return (this.page - 1) * this.perPage;
+  }
+}
+```
+
+```typescript
+// src/common/helpers/paginate.helper.ts
+import { PaginationMeta } from '../interceptors/response.interceptor';
+
+export function paginate<T>(
+  data: T[],
+  total: number,
+  page: number,
+  perPage: number,
+): { data: T[]; meta: PaginationMeta } {
+  return {
+    data,
+    meta: {
+      total,
+      page,
+      perPage,
+      totalPages: Math.ceil(total / perPage),
+    },
+  };
+}
+```
+
+## Uso no Controller
+
+```typescript
+// Resposta paginada
+@Get()
+async findAll(@Query() pagination: PaginationDto) {
+  const [users, total] = await this.usersService.findAll(pagination);
+  return paginate(users, total, pagination.page, pagination.perPage);
+}
+
+// Resposta simples (envolvida automaticamente pelo interceptor)
+@Get(':id')
+async findOne(@Param('id', ParseUUIDPipe) id: string) {
+  return this.usersService.findOne(id);
+}
+
+// Criação
+@Post()
+@HttpCode(201)
+async create(@Body() dto: CreateUserDto) {
+  return this.usersService.create(dto);
+}
+
+// Sem conteúdo
+@Delete(':id')
+@HttpCode(204)
+async remove(@Param('id', ParseUUIDPipe) id: string) {
+  await this.usersService.remove(id);
+}
+```
+
+## Nunca retornar senha ou dados sensíveis
+
+```typescript
+// ❌ ERRADO — senha no response
+return user;
+
+// ✅ CORRETO — excluir campos sensíveis
+const { password, hashedRefreshToken, ...result } = user;
+return result;
+
+// ✅ ALTERNATIVA — usar @Exclude no Prisma result
+// Configurar class-transformer no main.ts:
+app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
+```
+
+## Checklist de contratos de API
+
+- [ ] Todos os endpoints retornam `{ data, meta }` via interceptor global
+- [ ] Listas paginadas usam `PaginationDto` e `paginate()` helper
+- [ ] Erros usam as exceções padrão do NestJS (nunca retornar erro genérico)
+- [ ] `password` e `hashedRefreshToken` NUNCA no response
+- [ ] Swagger configurado com exemplos de request/response
+- [ ] IDs sempre UUID — nunca sequencial

package/templates/.claude/skills/react/setup.md

@@ -2,6 +2,20 @@
 
 Complementa o **SKILL.md** com arquivos base: API, auth e rotas.
 
+## ⚠️ SEGURANÇA — Armazenamento de tokens (OWASP A02)
+
+> **Nunca use `localStorage` para armazenar tokens JWT.**
+> localStorage é acessível por qualquer JavaScript da página — vulnerável a XSS.
+
+**Estratégia correta:**
+- **Access token** → memória (variável de estado React, nunca persistida)
+- **Refresh token** → cookie `httpOnly` (configurado pelo backend, inacessível via JS)
+- `withCredentials: true` no Axios para enviar o cookie automaticamente
+
+O backend deve configurar o refresh token como cookie `httpOnly; Secure; SameSite=Strict`.
+
+---
+
 ## src/services/api.ts
 
 ```typescript
@@ -9,22 +23,39 @@ import axios from 'axios';
 
 const api = axios.create({
   baseURL: import.meta.env.VITE_API_URL ?? 'http://localhost:3000/api/v1',
-  withCredentials: true,
+  withCredentials: true, // envia cookie httpOnly com refresh token automaticamente
 });
 
+// O access token fica apenas em memória — injetado pelo AuthContext
+let _accessToken: string | null = null;
+
+export const setAccessToken = (token: string | null) => { _accessToken = token; };
+
 api.interceptors.request.use((config) => {
-  const token = localStorage.getItem('access_token');
-  if (token) config.headers.Authorization = `Bearer ${token}`;
+  if (_accessToken) config.headers.Authorization = `Bearer ${_accessToken}`;
   return config;
 });
 
 api.interceptors.response.use(
   (r) => r,
   async (error) => {
-    // Opcional: refresh token + fila de retries — alinhar com backend
-    if (error.response?.status === 401) {
-      localStorage.removeItem('access_token');
-      window.location.href = '/login';
+    const original = error.config;
+    if (error.response?.status === 401 && !original._retry) {
+      original._retry = true;
+      try {
+        // Tenta renovar via cookie httpOnly (sem enviar token no body)
+        const { data } = await axios.post(
+          `${import.meta.env.VITE_API_URL}/auth/refresh`,
+          {},
+          { withCredentials: true },
+        );
+        setAccessToken(data.access_token);
+        original.headers.Authorization = `Bearer ${data.access_token}`;
+        return api(original);
+      } catch {
+        setAccessToken(null);
+        window.location.href = '/login';
+      }
     }
     return Promise.reject(error);
   },
@@ -43,15 +74,15 @@ import {
   useCallback,
   type ReactNode,
 } from 'react';
-import api from '../services/api';
+import api, { setAccessToken } from '../services/api';
 
-type User = { id: string; email: string; name: string };
+type User = { id: string; email: string; name: string; role: string };
 
 type AuthContextValue = {
   user: User | null;
   loading: boolean;
   login: (email: string, password: string) => Promise<void>;
-  logout: () => void;
+  logout: () => Promise<void>;
 };
 
 const AuthContext = createContext<AuthContextValue | null>(null);
@@ -64,16 +95,22 @@ export function AuthProvider({ children }: { children: ReactNode }) {
     setLoading(true);
     try {
       const { data } = await api.post('/auth/login', { email, password });
-      localStorage.setItem('access_token', data.access_token);
+      // Access token apenas em memória — NÃO salvar em localStorage
+      setAccessToken(data.access_token);
       setUser(data.user);
+      // O refresh token é salvo como cookie httpOnly pelo backend automaticamente
     } finally {
       setLoading(false);
     }
   }, []);
 
-  const logout = useCallback(() => {
-    localStorage.removeItem('access_token');
-    setUser(null);
+  const logout = useCallback(async () => {
+    try {
+      await api.post('/auth/logout'); // invalida refresh token no banco + limpa cookie
+    } finally {
+      setAccessToken(null);
+      setUser(null);
+    }
   }, []);
 
   return (
@@ -150,4 +187,14 @@ createRoot(document.getElementById('root')!).render(
 );
 ```
 
+## Checklist de segurança de auth no frontend
+
+- [ ] Access token NUNCA em localStorage ou sessionStorage
+- [ ] Access token apenas em variável de módulo (memória)
+- [ ] Refresh token configurado como cookie httpOnly pelo backend
+- [ ] `withCredentials: true` no Axios
+- [ ] Interceptor de 401 com retry automático via refresh
+- [ ] Logout invalida token no backend + limpa estado local
+- [ ] Não logar tokens em console.log
+
 Substitua os placeholders de página pelos componentes reais em `pages/`.

package/templates/.claude/skills/testing/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: testing
+description: Estratégia e implementação de testes para NestJS + React + React Native. Use quando o desenvolvedor precisar configurar testes unitários, de integração ou e2e, escrever specs, mockar dependências ou configurar cobertura de código.
+---
+
+# Testing
+
+Stack: Jest (backend) · Vitest (frontend) · Supertest · Testing Library · Playwright (e2e)
+
+## Pirâmide de testes adotada
+
+```
+        /\
+       /e2e\        ← Playwright — fluxos críticos (login, checkout)
+      /------\
+     /integra-\     ← Supertest — endpoints reais com banco de teste
+    /  ção     \
+   /------------\
+  /  unitários   \  ← Jest/Vitest — lógica isolada, services, utils
+ /________________\
+```
+
+> Regra: mais unitários, menos e2e. E2e é caro — use apenas para fluxos críticos de negócio.
+
+## Backend — Jest + Supertest
+
+```bash
+# Já vem com NestJS — verificar se está instalado
+npm install --save-dev jest @types/jest ts-jest supertest @types/supertest
+```
+
+```typescript
+// jest.config.ts
+export default {
+  moduleFileExtensions: ['js', 'json', 'ts'],
+  rootDir: 'src',
+  testRegex: '.*\\.spec\\.ts$',
+  transform: { '^.+\\.(t|j)s$': 'ts-jest' },
+  collectCoverageFrom: ['**/*.(t|j)s'],
+  coverageDirectory: '../coverage',
+  testEnvironment: 'node',
+};
+```
+
+## Frontend — Vitest + Testing Library
+
+```bash
+npm install --save-dev vitest @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom
+```
+
+```typescript
+// vite.config.ts — adicionar
+test: {
+  globals: true,
+  environment: 'jsdom',
+  setupFiles: './src/test/setup.ts',
+}
+```
+
+```typescript
+// src/test/setup.ts
+import '@testing-library/jest-dom';
+```
+
+## E2E — Playwright
+
+```bash
+npm install --save-dev @playwright/test
+npx playwright install chromium
+```
+
+## Arquivos detalhados desta skill
+
+- **backend.md** — Testes unitários e de integração para NestJS (services, guards, controllers)
+- **frontend.md** — Testes de componentes React com Testing Library
+- **e2e.md** — Fluxos e2e com Playwright
+
+Leia os arquivos de detalhe para implementar cada camada da pirâmide.

package/templates/.claude/skills/testing/backend.md

@@ -0,0 +1,161 @@
+# Testing — Backend (NestJS + Jest)
+
+## Teste unitário — Service
+
+```typescript
+// src/auth/auth.service.spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { AuthService } from './auth.service';
+import { PrismaService } from '../prisma/prisma.service';
+import { JwtService } from '@nestjs/jwt';
+import { ConfigService } from '@nestjs/config';
+import * as bcrypt from 'bcrypt';
+
+const mockPrisma = {
+  user: {
+    findUnique: jest.fn(),
+    create: jest.fn(),
+    update: jest.fn(),
+  },
+};
+
+describe('AuthService', () => {
+  let service: AuthService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        AuthService,
+        { provide: PrismaService, useValue: mockPrisma },
+        { provide: JwtService, useValue: { signAsync: jest.fn().mockResolvedValue('token') } },
+        { provide: ConfigService, useValue: { get: jest.fn().mockReturnValue('secret') } },
+      ],
+    }).compile();
+
+    service = module.get<AuthService>(AuthService);
+  });
+
+  afterEach(() => jest.clearAllMocks());
+
+  describe('login', () => {
+    it('deve retornar tokens com credenciais válidas', async () => {
+      const hashedPassword = await bcrypt.hash('senha123', 12);
+      mockPrisma.user.findUnique.mockResolvedValue({
+        id: 'uuid-1',
+        email: 'user@test.com',
+        password: hashedPassword,
+        role: 'USER',
+      });
+      mockPrisma.user.update.mockResolvedValue({});
+
+      const result = await service.login('user@test.com', 'senha123');
+
+      expect(result).toHaveProperty('access_token');
+      expect(result).toHaveProperty('refresh_token');
+    });
+
+    it('deve lançar UnauthorizedException com credenciais inválidas', async () => {
+      mockPrisma.user.findUnique.mockResolvedValue(null);
+
+      await expect(service.login('x@x.com', 'errado')).rejects.toThrow(
+        'Credenciais inválidas',
+      );
+    });
+  });
+});
+```
+
+## Teste de integração — Controller com banco real
+
+```typescript
+// test/auth.e2e-spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import * as request from 'supertest';
+import { AppModule } from '../src/app.module';
+import { PrismaService } from '../src/prisma/prisma.service';
+
+describe('AuthController (integração)', () => {
+  let app: INestApplication;
+  let prisma: PrismaService;
+
+  beforeAll(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = module.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
+    await app.init();
+
+    prisma = module.get<PrismaService>(PrismaService);
+  });
+
+  afterAll(async () => {
+    await prisma.$executeRaw`TRUNCATE TABLE users CASCADE`;
+    await app.close();
+  });
+
+  describe('POST /auth/register', () => {
+    it('deve registrar um novo usuário', () => {
+      return request(app.getHttpServer())
+        .post('/auth/register')
+        .send({ name: 'Teste', email: 'teste@email.com', password: 'Senha@123' })
+        .expect(201)
+        .expect((res) => {
+          expect(res.body.data).toHaveProperty('id');
+          expect(res.body.data).not.toHaveProperty('password');
+        });
+    });
+
+    it('deve rejeitar email duplicado', () => {
+      return request(app.getHttpServer())
+        .post('/auth/register')
+        .send({ name: 'Teste', email: 'teste@email.com', password: 'Senha@123' })
+        .expect(409);
+    });
+  });
+
+  describe('POST /auth/login', () => {
+    it('deve retornar tokens com credenciais válidas', async () => {
+      const res = await request(app.getHttpServer())
+        .post('/auth/login')
+        .send({ email: 'teste@email.com', password: 'Senha@123' })
+        .expect(200);
+
+      expect(res.body.data).toHaveProperty('access_token');
+      // Refresh token deve vir como cookie httpOnly, não no body
+      expect(res.headers['set-cookie']).toBeDefined();
+    });
+  });
+});
+```
+
+## Banco de dados de teste
+
+```env
+# .env.test
+DATABASE_URL="postgresql://user:pass@localhost:5432/myapp_test"
+```
+
+```json
+// package.json
+{
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:e2e": "dotenv -e .env.test -- jest --config ./test/jest-e2e.json",
+    "test:e2e:watch": "dotenv -e .env.test -- jest --config ./test/jest-e2e.json --watch"
+  }
+}
+```
+
+## Checklist de testes backend
+
+- [ ] Cada service tem `.spec.ts` com casos de sucesso e erro
+- [ ] Banco de dados de teste separado (`.env.test`)
+- [ ] Dados de teste limpos após cada suite (`afterAll` com TRUNCATE)
+- [ ] Senhas nunca hardcoded nos testes — usar factory functions
+- [ ] Cobertura mínima de 70% nos services
+- [ ] Guards testados isoladamente