Contribuindo com o MangoStudio

Obrigado pelo seu interesse em contribuir com o MangoStudio!

🇺🇸 Read in English

Pré-requisitos

Bun 1.4.3 ou mais recente — bun upgrade ou curl -fsSL https://bun.sh/install | bash na primeira instalação
Rust 1.99.0 ou mais recente via rustup — curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh. O hub inicia o Local como o mangostudio-runtime construído com cargo; o bun run dev o compila antes, e o rust-toolchain.toml fixa a versão
Git com assinatura GPG configurada (veja Diretrizes de Commit)

O repositório fixa o Bun 1.4.3. O pin passou para a linha 1.4.x na 1.4.0, a release que tornou o runtime pós-reescrita disponível de forma geral; até então ele seguia o canal canary. O .bun-version é o que a CI instala, e o packageManager precisa indicar a mesma versão — veja docs/reference/tooling.md.

Configuração do Ambiente

# Clone o repositório
git clone <repo-url>
cd mangostudio

# Instale todas as dependências do workspace
bun install

# Copie e configure
mkdir -p ~/.mango
cp .mango/config.toml.example ~/.mango/config.toml
cp .mango/.env.example ~/.mango/.env
# Edite ~/.mango/.env e adicione suas chaves de API

Fluxo de Desenvolvimento

# Inicia o servidor de dev (API e frontend em :3001)
bun run dev

# Ou inicie cada workspace individualmente
bun run dev --api
bun run dev --frontend

Mapa da Documentação

../README.md — ponto de entrada da árvore de documentação
../guides/contributor-quickstart.md — caminho mais curto para começar a contribuir
../reference/testing.md — taxonomia de testes, runners e regras de suporte
../reference/agent-playbooks.md — mapa de arquivos por feature para trabalho direcionado

Padrões de Código

Consulte AGENTS.md para o guia completo de estilo, convenções de nomes, regras de i18n e diretrizes de testes. Pontos principais:

TypeScript em todo o projeto — nenhum arquivo .js puro
Indentação de 2 espaços, aspas simples, ponto e vírgula
Todas as strings visíveis ao usuário devem vir de @mangostudio/shared/i18n — nunca codifique texto diretamente
Hooks que contêm JSX devem usar a extensão .tsx
Arquivos CLAUDE.md com @imports
Agentes de IA: use AGENTS.md como fonte de orientações agnósticas
Extras só do Cursor (incluindo notas da VM Cursor Cloud) ficam em .cursor/rules/. Não duplique AGENTS.md lá; o Cursor já carrega esse arquivo automaticamente.

Executando os Testes

# Qualidade de código
bun run check

# Todas as suítes
bun run test

# Apenas unitários
bun run test --unit

# Apenas integração
bun run test --integration

# Setup end-to-end, depois teste
bun run test:e2e:setup
bun run test --e2e

Checks e Verificação de Tipos

bun run check

Executa Biome, dprint, verificação de dependências circulares e verificação de tipos TypeScript em todos os workspaces.

Build

bun run build

Gera o build do frontend com Bun.build() (apps/frontend/build.ts) por padrão. Use bun run build --binary para binários standalone.

Diretrizes de Commit

Este projeto usa Conventional Commits. Todo commit deve ser assinado com GPG e incluir um sign-off:

git commit -S -s -m "feat(scope): resumo imperativo curto"

Tipos comuns: feat, fix, chore, test, docs, refactor, ci.

Mantenha cada commit com escopo único. Prefira vários commits pequenos a um único commit grande.

Todas as mensagens de commit devem ser escritas em inglês.

Template de Mensagem de Commit

Configure o Git para pré-preencher o editor de commit com o template do projeto:

git config commit.template .gitmessage

Esta é uma configuração local única. O template está em .gitmessage na raiz do repositório.

Processo de Pull Request

Crie um branch a partir de main com um nome descritivo (ex: feat/add-gallery-empty-state).
Execute a suíte de validação completa localmente antes de fazer push:
```
bun run check && bun run test
```
Abra um PR contra main e preencha o template de PR.
PRs exigem que todas as verificações de CI passem antes do merge.
Screenshots ou GIFs são obrigatórios para mudanças de UI.

Migrações de Banco de Dados

bun run --filter @mangostudio/api migrate

Se sua mudança exigir uma migração de schema, adicione o arquivo de migração em apps/api/src/db/migrations/ e execute o comando acima localmente para verificar que ele é aplicado corretamente.

Segurança

Nunca faça commit de arquivos .env populados ou chaves de API. O GEMINI_API_KEY é acessado apenas no lado do servidor e não deve ser exposto ao bundle do frontend.

Se você descobrir uma vulnerabilidade de segurança, por favor reporte-a de forma privada em vez de abrir uma issue pública.