W1: Claude Code Solo

# CLAUDE.md — W1: Claude Code Solo

## Stack
- Runtime: Node.js 22 + TypeScript 5 strict mode
- Framework: (adapte ao seu projeto)
- ORM: Prisma / TypeORM
- Testes: Vitest (unit + integration) + Cypress (E2E)
- Load: k6

## Comandos principais
```bash
npm run dev        # desenvolvimento local
npm run test:unit  # npx vitest run --testPathPattern='*.unit.test'
npm run test:int   # npx vitest run --testPathPattern='*.integration.test'
npm run test:e2e   # npx cypress run --headless
npm run build      # build de produção
npm audit          # auditoria de segurança
```

## Arquitetura: Hexagonal (Ports & Adapters)
- src/domain/        — entidades, use cases, value objects (SEM imports de infra)
- src/ports/         — interfaces (IUserRepository, IMailService, etc.)
- src/adapters/      — implementações concretas (HTTP, DB, Mail)
- src/app/           — composição de dependências (DI container)

Regra absoluta: domain NUNCA importa de adapters.
Dependa de interfaces (ports), nunca de implementações concretas.

## SOLID — diretivas obrigatórias
- S: cada classe/função tem UMA razão para mudar
- O: use strategy/decorator para variações, não if/else
- L: subtipos substituem base sem quebrar comportamento
- I: interfaces pequenas e específicas — nunca interface "God"
- D: construtor recebe interfaces, nunca instancia dependências diretamente

## TDD — sequência obrigatória
1. Escreve o TESTE primeiro (deve falhar — RED)
2. Implementa o MÍNIMO para passar (GREEN)
3. Refatora sem quebrar (REFACTOR)
NUNCA implementar sem teste existente e falhando primeiro.

## OWASP Top 10 — checklist de cada feature
- A01: toda rota verifica autenticação + autorização (RBAC)
- A02: secrets apenas em env vars — nunca hardcoded
- A03: queries sempre parametrizadas — proibido string concatenation
- A04: threat model na fase de design
- A06: npm audit como gate pré-PR
- A07: JWT validado em cada request; tokens expiram em 15min (access) / 7d (refresh)

## Context window discipline
- Máximo de 80K tokens ativos no orquestrador
- Execute /compact entre fases (após planning, após implementação, após review)
- Handoffs via PLAN.md e CONTEXT.md — nunca in-memory
- Destrua a sessão após cada fase completa se contexto > 60K

## Proibições
- Nunca usar `any` em TypeScript
- Nunca fazer `git add .` — sempre `git add -p`
- Nunca implementar sem teste falhando primeiro
- Nunca commitar com npm audit de alta severidade aberto
- Nunca fazer strings SQL por concatenação

// src/domain/__tests__/auth.unit.test.ts
import { describe, it, expect, vi } from 'vitest'
import { AuthService } from '../auth.domain'
import type { ITokenRepository } from '../../ports/ITokenRepository'
import type { IUserRepository } from '../../ports/IUserRepository'

describe('AuthService', () => {
  const mockUserRepo: IUserRepository = {
    findByEmail: vi.fn(),
    save: vi.fn(),
  }
  const mockTokenRepo: ITokenRepository = {
    save: vi.fn(),
    findByRefreshToken: vi.fn(),
    revoke: vi.fn(),
  }

  it('should return access and refresh tokens on valid credentials', async () => {
    const hashedPassword = '$2b$10$validhash'
    mockUserRepo.findByEmail = vi.fn().mockResolvedValue({
      id: 'user-123',
      email: 'dev@example.com',
      passwordHash: hashedPassword,
      role: 'developer',
    })

    const sut = new AuthService(mockUserRepo, mockTokenRepo)
    const result = await sut.login('dev@example.com', 'correct-password')

    expect(result.accessToken).toBeDefined()
    expect(result.refreshToken).toBeDefined()
    expect(result.expiresIn).toBe(900) // 15 minutos
  })

  it('should throw UnauthorizedError on invalid password', async () => {
    mockUserRepo.findByEmail = vi.fn().mockResolvedValue({
      id: 'user-123',
      email: 'dev@example.com',
      passwordHash: '$2b$10$validhash',
      role: 'developer',
    })

    const sut = new AuthService(mockUserRepo, mockTokenRepo)
    await expect(sut.login('dev@example.com', 'wrong-password'))
      .rejects.toThrow('UnauthorizedError')
  })

  it('should throw UnauthorizedError on unknown email', async () => {
    mockUserRepo.findByEmail = vi.fn().mockResolvedValue(null)

    const sut = new AuthService(mockUserRepo, mockTokenRepo)
    await expect(sut.login('unknown@example.com', 'any-password'))
      .rejects.toThrow('UnauthorizedError')
  })
})

# Confirmar RED — deve falhar (AuthService nao existe ainda)
npx vitest run src/domain/__tests__/auth.unit.test.ts
# FAIL: Cannot find module '../auth.domain'

// src/domain/auth.domain.ts
import bcrypt from 'bcrypt'
import jwt from 'jsonwebtoken'
import type { IUserRepository } from '../ports/IUserRepository'
import type { ITokenRepository } from '../ports/ITokenRepository'

export class UnauthorizedError extends Error {
  constructor() { super('UnauthorizedError'); this.name = 'UnauthorizedError' }
}

export interface AuthResult {
  accessToken: string
  refreshToken: string
  expiresIn: number
}

export class AuthService {
  constructor(
    private readonly userRepo: IUserRepository,    // D: depende de interface
    private readonly tokenRepo: ITokenRepository,  // D: depende de interface
  ) {}

  async login(email: string, password: string): Promise<AuthResult> {
    const user = await this.userRepo.findByEmail(email)
    if (!user) throw new UnauthorizedError()

    const valid = await bcrypt.compare(password, user.passwordHash)
    if (!valid) throw new UnauthorizedError()

    const accessToken = jwt.sign(
      { sub: user.id, role: user.role },
      process.env.JWT_SECRET!,
      { expiresIn: '15m' }
    )
    const refreshToken = crypto.randomUUID()

    await this.tokenRepo.save({ userId: user.id, refreshToken })

    return { accessToken, refreshToken, expiresIn: 900 }
  }
}

# Confirmar GREEN — todos os testes devem passar
npx vitest run src/domain/__tests__/auth.unit.test.ts
# PASS: 3 tests passed

// Melhorias SOLID aplicadas pelo Claude no refactor:
// S: extrair geração de tokens para TokenFactory (responsabilidade única)
// O: comportamento de login extensível via strategy (ex: OAuth2) sem alterar AuthService
// I: IUserRepository e ITokenRepository separados (interface segregation)

// src/domain/token.factory.ts — S: responsabilidade única de geração
import jwt from 'jsonwebtoken'

export class TokenFactory {
  createAccessToken(userId: string, role: string): string {
    return jwt.sign(
      { sub: userId, role },
      process.env.JWT_SECRET!,
      { expiresIn: '15m' }
    )
  }

  createRefreshToken(): string {
    return crypto.randomUUID()
  }
}

// auth.domain.ts atualizado — delega geração ao TokenFactory
export class AuthService {
  constructor(
    private readonly userRepo: IUserRepository,
    private readonly tokenRepo: ITokenRepository,
    private readonly tokenFactory: TokenFactory,  // D: injetado
  ) {}

  async login(email: string, password: string): Promise<AuthResult> {
    const user = await this.userRepo.findByEmail(email)
    if (!user) throw new UnauthorizedError()

    const valid = await bcrypt.compare(password, user.passwordHash)
    if (!valid) throw new UnauthorizedError()

    const accessToken = this.tokenFactory.createAccessToken(user.id, user.role)
    const refreshToken = this.tokenFactory.createRefreshToken()

    await this.tokenRepo.save({ userId: user.id, refreshToken })

    return { accessToken, refreshToken, expiresIn: 900 }
  }
}

# Confirmar que refactor nao quebrou nada
npx vitest run src/domain/__tests__/auth.unit.test.ts
# PASS: 3 tests passed (com TokenFactory mockado)

# Verificar uso atual de tokens (estimativa via /status se disponivel)
# No Claude Code, use o comando built-in:
/compact

# O Claude resumira o contexto atual mantendo apenas
# o essencial — arquivos modificados, decisoes tomadas,
# proximo passo. Estado de longa duracao vai para arquivos.

# CONTEXT.md — Handoff de Sessao

## Feature em andamento
[Nome da feature — ex: JWT Authentication]

## Estado atual
- Fase: [Discovery | Planning | TDD Loop | Auto-review | Testing Gate | Deploy]
- Ultimo commit: [hash] — [mensagem]
- Testes passando: [X unit, Y integration, Z e2e]

## Arquivos modificados nesta sessao
- src/domain/auth.domain.ts — AuthService implementado (GREEN)
- src/domain/token.factory.ts — TokenFactory extraido (REFACTOR)
- src/ports/ITokenRepository.ts — interface criada
- src/domain/__tests__/auth.unit.test.ts — 3 testes, todos passando

## Decisoes tomadas
- Optamos por TokenFactory separado (SOLID-S) em vez de metodo privado
- JWT expira em 15min (access) e refresh e UUID v4 sem expiracao automatica
- Refresh token revogado no DB ao usar (one-time use)

## Proximo passo
Implementar o adapter HTTP: src/adapters/http/auth.routes.ts
Teste de integracao: src/adapters/__tests__/auth.integration.test.ts
Deve cobrir: POST /auth/login, POST /auth/refresh, POST /auth/logout

## Blockers / Riscos
- Nenhum blocker identificado
- Risco: JWT_SECRET nao configurado em .env.test — verificar antes dos integration tests

## Como retomar
```bash
claude
# "Leia CONTEXT.md, PLAN.md e os arquivos listados em 'Arquivos modificados'.
#  Estamos na fase de Testing Gate. Escreva o teste de integracao
#  para auth.routes.ts conforme descrito em Proximo passo."
```

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "node scripts/quality-gate.mjs \"$CLAUDE_TOOL_INPUT_FILE_PATH\""}]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "node scripts/bash-guard.mjs"}]
      }
    ]
  }
}