Como contribuir

Contribuir com o Nodaro significa enviar código para o repositório público, github.com/nodaroai/app.nodaro.ai, como um pull request. O Nodaro tem o código-fonte disponível (source-available) sob a Nodaro Sustainable Use License. Esta página trata do ambiente de desenvolvimento, das branches, dos pull requests, dos testes e do contrato de colaborador.

Para rodar o Nodaro no seu próprio servidor, comece pelo Início rápido. Para criar algo sobre a API, veja o SDK.

O repositório

O repositório é um monorepo com npm workspaces:

As regras da casa estão no CLAUDE.md, na raiz do repositório: os padrões de código, o checklist para adicionar um provedor de modelos e o checklist para adicionar um nó. Leia esse arquivo antes de um pull request que não seja trivial. A página Arquitetura explica como as partes se encaixam.

Preparar o ambiente de desenvolvimento

Você precisa do Node.js 22 ou mais recente, com o npm.

git clone https://github.com/nodaroai/app.nodaro.ai
cd app.nodaro.ai
npm install        # installs every workspace

cp .env.example .env

echo "INTERNAL_ORCHESTRATOR_SECRET=$(openssl rand -hex 32)" >> .env
echo "NODARO_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

npm -w @nodaro/shared run build

# Terminal 1: the API on port 9000
cd backend
npm run dev

# Terminal 2: the frontend on port 3000, which forwards /v1/* to port 9000
cd frontend
npm run dev

Padrões de código

As regras mais importantes do CLAUDE.md:

• Tamanho dos arquivos. De 200 a 400 linhas é o normal, e 800 é o limite máximo. Divida um arquivo que cresça além disso.
• Nada de console.log em código de produção. Use os padrões de logger existentes.
• Conventional commits: feat:, fix:, refactor:, docs:, chore:, test:, com uma linha de assunto específica.
• Verifique os tipos antes de cada commit, com npx tsc --noEmit em backend/ e em frontend/. A CI bloqueia os pull requests que não passam na verificação de tipos.
• Plugins do Fastify, não routers do Express. Todo arquivo de rota exporta uma função assíncrona que recebe a instância do Fastify.
• Todo endpoint da API tem um schema Zod, sem exceções. O schema valida a requisição e também gera o documento OpenAPI.
• Estado do frontend: React Query para o estado do servidor, Zustand para o estado da interface e React Flow para o estado do canvas. Não os misture.
• Nunca faça mutação de objetos ou arrays. Sempre crie cópias novas: tanto o Zustand quanto o React Flow dependem da igualdade por referência.

Branches e pull requests

• O repositório tem duas branches permanentes: dev, para staging, e main, para produção.
• Faça um fork do repositório, crie a branch a partir de dev e abra o pull request para dev. Nunca crie uma branch a partir de main nem faça commits diretamente nela.
• Dê à branch um nome pelo tipo dela: feat/, fix/, refactor/, docs/, chore/ ou test/, por exemplo feat/whisper-tts-node.
• As mudanças mescladas rodam primeiro na instância de staging, next.nodaro.ai. Depois de um período de observação de cerca de 24 horas, um mantenedor promove a dev para a main.

No seu pull request:

• Vincule a issue do GitHub a que ele se refere.
• Adicione capturas de tela ou GIFs para mudanças na interface.
• Siga o checklist de nós do CLAUDE.md quando adicionar ou alterar um nó.
• Adicione um changeset quando alterar um pacote publicado. Veja Changesets.

Testes

Cada workspace tem a própria suíte Vitest. Rode tudo a partir da raiz do repositório, ou um workspace de cada vez:

npm test                       # every workspace's test script

npm -w @nodaro/shared test     # pure-logic unit tests
npm -w @nodaro/sdk test        # SDK contract tests against a mocked API
cd backend && npm test         # route and service tests
cd frontend && npm test        # component and hook tests

O que testar:

• Rotas da API — o caminho principal, mais os casos extremos que o seu schema lista. Faça mock do Supabase e dos provedores de IA: um teste unitário nunca chama a API real de um provedor. A maioria dos testes existentes tem uma configuração que você pode copiar.
• Componentes do frontend — testes de fumaça (smoke tests) com o React Testing Library. Coloque a lógica pesada em hooks ou helpers, onde ela pode ser testada isoladamente, e não teste os detalhes internos do React Flow nem os stores do Zustand.
• O pacote compartilhado — testes unitários de funções puras. As exportações dele precisam continuar serializáveis entre o frontend e o backend.

A CI roda tsc --noEmit, o Vitest e uma pequena etapa de lint. Se um teste falhar localmente, mas passar na CI, ou o contrário, abra uma issue com os passos para reproduzir o problema.

Verificações da saída do ffmpeg

Os testes unitários comuns verificam os argumentos passados ao ffmpeg, não o que o ffmpeg renderiza. Uma suíte de caracterização separada renderiza arquivos de teste (fixtures) por todas as operações que usam o ffmpeg. Depois, ela compara propriedades medidas da saída decodificada com valores de referência registrados no repositório: energia, espectro, decaimento, duração e brilho por quadro.

A suíte fica fora do npm test: os números dela só valem para a build exata do ffmpeg fixada na imagem de produção. Rode-a dentro dessa imagem:

backend/scripts/characterize-in-image.sh check   # compare with the reference values
backend/scripts/characterize-in-image.sh bless   # rewrite the reference values, on purpose only
cd backend && npm run characterize:report -- --against ffmpeg-X.json

Se você alterar uma operação que usa o ffmpeg, rode check antes de abrir o pull request. A CI também o roda. Se a sua mudança tiver a intenção de alterar a saída renderizada, faça o bless dentro da imagem e faça commit dos novos valores de referência, com uma explicação de cada medida que mudou. Nunca edite os valores de referência manualmente, e nunca faça o bless com um ffmpeg local: a proteção de versão da suíte o rejeita.

Adicionar um nó ou um provedor de modelos

Adicionar um nó mexe em muitos arquivos: uma rota da API, um componente do frontend, o executor e vários registros. Esquecer um deles dá resultados confusos, como um nó que não aparece em um dos menus de nós ou um botão Executar que não faz nada. Siga o checklist New Node Registration do CLAUDE.md, passo a passo.

Adicionar um modelo a um nó existente é um trabalho mais curto, com o próprio checklist Provider Enum Sync no CLAUDE.md. A etapa mais esquecida é o schema da rota da API: sem ele, o editor oferece uma opção que a API rejeita com 400.

Changesets

Três pacotes são publicados no npm: @nodaro/shared, @nodaro/sdk e @nodaro/cli. As versões usam o Changesets e são automatizadas. Quando a sua mudança afeta um deles:

npx changeset

Escolha os pacotes, o tipo de incremento (patch, minor ou major) e um resumo de uma linha. Faça commit do arquivo que ele grava em .changeset/ junto com o seu pull request. A verificação Changeset Guard reprova os pull requests que alteram um pacote publicado sem um changeset. Para uma mudança que não precisa de nota de versão, use npx changeset --empty.

Todo o resto é automático. Na dev, um pull request Version Packages reúne os changesets pendentes. Quando a dev é promovida para a main, o workflow de release publica as novas versões no npm, cria as tags delas, cria as releases no GitHub e recompila os binários independentes da CLI. Os workspaces backend, frontend e Remotion nunca são publicados e não precisam de changeset.

Código de conduta

Seja gentil, trate todos com respeito e presuma boa-fé. O projeto segue o Contributor Covenant 2.1, em CODE_OF_CONDUCT.md. Assédio de qualquer tipo é motivo para remoção do projeto.

• Critique o código, não as pessoas.
• Discorde sem ser grosseiro: “Acho que o padrão X ficaria mais limpo aqui por causa de Y” funciona; “isso está ruim” não.
• Mantenedores que revisam o trabalho de quem contribui pela primeira vez: tenham paciência.

Onde perguntar

• GitHub Discussions — perguntas abertas, ideias e coisas que você criou com o Nodaro. Prefira-o ao Issues para tudo o que não for um bug.
• GitHub Issues — relatos de bugs e pedidos de recursos.
• Problemas de segurança — relate-os por um aviso de segurança privado (security advisory) no GitHub.

Evite mandar e-mails particulares aos mantenedores sobre o projeto: as respostas públicas ajudam todo mundo. O contato particular é adequado para relatos de segurança e conflitos de interesse.

Licença e contrato de colaborador

O repositório tem quatro níveis de licença. A maior parte do código está sob a Nodaro Sustainable Use License. O código em qualquer pasta ee e nos arquivos com .ee. no nome está sob a Nodaro Enterprise License. O @nodaro/prompts está sob a FSL-1.1-Apache-2.0, e @nodaro/sdk, @nodaro/shared e @nodaro/cli estão sob a Apache 2.0. Veja Licença.

Onde o código novo entra. Cada versão publicada dos pacotes Apache é uma concessão irrevogável. A nova engenharia de prompts, os catálogos e as predefinições ficam no @nodaro/prompts ou em backend/. Adicione ao @nodaro/shared só o que a API pública e o contrato do SDK precisam, como tipos, enums dos payloads da API e validação compartilhada com os usuários da API, ou o que você publica de propósito para reutilização. Diga qual dos dois casos se aplica no seu pull request.

O contrato de colaborador. Ao enviar uma contribuição, você concorda com o Nodaro Contributor License Agreement. O mesmo contrato cobre contribuições individuais e corporativas: a seção 2 dele trata da permissão do seu empregador. O bot cla-assistant pede que você o assine no seu primeiro pull request. Se você contribui em nome de um empregador, verifique se a política de propriedade intelectual dele permite isso. O contrato permite que o Nodaro licencie a sua contribuição sob qualquer uma das licenças dele, inclusive movê-la entre a Sustainable Use License e a Enterprise License.