Convenções de Código

Linter & Formatter

Todos os repositórios usam Biome 2.4.9 (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 e obrigatorio em todos os repos. O package.json deve ter:

{
  "engines": {
    "node": ">=24.14.1",
    "pnpm": ">=10.0.0"
  }
}

O monorepo SDK (front-cactus-core) tambem usa Turborepo para orquestracao de builds e cache de tarefas.

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

Regra: app/config no template

A pasta app/config no template (front-web-base) deve conter somente dados estáticos de configuração por brand:

Permitido	Proibido
Objetos de config exportados	Hooks (use*)
Tipos e interfaces de config	Parsers e helpers de lógica
Re-exports de tipos do SDK	Dados globais (país, DDI, currency)

Hooks devem ficar em app/hooks/. Dados globais (catálogo de países, DDI, mapeamento moeda→país) vêm exclusivamente do SDK @cactus-agents/*.

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)