Convenções de Código

Linter & Formatter

Todos os repositórios usam Biome 1.9.4 (substitui ESLint + Prettier).

pnpm lint        # Verificar problemas
pnpm format      # Formatar código

Configuração em biome.json:

• Indent: spaces (2)
• Line width: 100
• JSX quote style: double
• Organize imports: habilitado

Commits

Padrão Conventional Commits com commitlint:

feat: add login modal
fix: handle 401 on profile fetch
refactor: extract brand transform helpers
docs: update auth flow documentation
chore: bump @cactus-agents/auth to 1.2.0

Prefixos:

Prefixo	Uso
feat	Nova funcionalidade
fix	Correção de bug
refactor	Mudança de código sem alterar comportamento
docs	Documentação
chore	Manutenção, deps, CI
test	Testes
style	Formatação (sem mudança de lógica)

Pre-commit

Husky + lint-staged roda biome check --write nos arquivos staged antes de cada commit.

Package manager

pnpm é obrigatório em todos os repos. O package.json deve ter:

{
  "engines": {
    "node": ">=20.14.0"
  }
}

TypeScript

• Strict mode habilitado em todos os pacotes
• Tipos explícitos em exports públicos
• any deve ser evitado — use unknown quando o tipo é desconhecido
• Tipos compartilhados ficam em @cactus-agents/types

Estrutura de pacotes (@cactus-agents/*)

Cada pacote segue:

packages/nome/
├── src/
│   ├── index.ts          # Exports públicos
│   ├── *.ts              # Implementação
│   └── types.ts          # Tipos do pacote
├── tests/
│   └── *.test.ts
├── package.json
├── tsconfig.json
├── tsup.config.ts        # Build: ESM + CJS + .d.ts
└── vitest.config.ts

Testes

• Vitest para todos os pacotes e apps
• React Testing Library para testes de componente
• Nome do arquivo: *.test.ts ou *.test.tsx
• Testes ficam em pasta tests/ ou ao lado do arquivo (*.test.ts)