Trabalhando na stack

Esta página é para quem está prestes a mudar o código. Ela diz onde o código está, como conseguir um ambiente de desenvolvimento e — a parte que vale ler com atenção — exatamente o que cada repositório verifica, porque os quatro componentes não verificam as mesmas coisas e um deles documenta um comando que não consegue rodar.

Onde o código está

O repositório do produto é zombie-crab-project, e quatro dos seus diretórios são repositórios Git separados trazidos como submódulos:

O próprio repositório do produto guarda os arquivos compose, a configuração de deploy sob deploy/, os Dockerfiles do gateway Mycelium e da sua UI de administração sob fungi/, este livro sob docs/book/, e as especificações sob .specs/.

Como eles são submódulos, um git clone simples te dá quatro diretórios vazios. Clone a cadeia inteira de uma vez:

git clone --recurse-submodules https://github.com/LepistaBioinformatics/zombie-crab-project.git
cd zombie-crab-project

Se você já clonou sem eles, git submodule update --init --recursive os preenche.

Um ambiente de desenvolvimento

O arquivo compose de desenvolvimento constrói todo serviço a partir do código-fonte, então os únicos pré-requisitos para rodar a stack são o Docker com o plugin Compose e uma chave de API de LLM. Copie deploy/standalone/.env.example para .env na raiz do repositório, preencha os tokens bearer, as chaves de API por agente e o segredo de bootstrap, e suba a stack. Instalação percorre isso em ordem, e Configuração cobre o que cada variável faz.

Duas coisas sobre esse build valem saber antes de você começar.

A primeira é que alguns builds rodam testes. crab-shell-proxy e crab-ganglion-harness rodam go vet e a sua suíte de testes completa dentro do build do Docker, antes de o binário ser linkado, então um teste falhando impede a stack de subir em vez de produzir uma imagem quebrada em silêncio. Esse é o comportamento pretendido para um arquivo compose de desenvolvimento, não um acidente.

A segunda é que as duas imagens de harness são produzidas por serviços que só constroem — picoclaw-image e ganglion-image — que constroem uma tag e saem, e o proxy espera pelos dois. Eles existem porque essas imagens não são serviços próprios e nada as puxa: docker system prune remove uma imagem não usada, e sem um serviço compose para reconstruí-la, todo agente que a usa ficaria morto até alguém lembrar de rodar docker build na mão.

Para trabalhar em um componente sem reconstruir tudo, você pode desenvolvê-lo nativamente contra o resto da stack. O webapp é o caso mais fácil — yarn dev na porta 3000 contra um gateway rodando — porque ele lê MYCELIUM_INTERNAL_URL e DATABASE_URL a cada requisição.

Os gates, repositório por repositório

Estas listas vêm dos workflows de cada repositório, do seu Dockerfile e do seu package.json. Onde um repositório não tem verificação automatizada, esta página diz isso em vez de sugerir um comando que nada impõe.

crab-ganglion-harness

O único repositório com um workflow de pull request que roda os testes. .github/workflows/ci.yml roda em cada pull request e em cada push para main:

gofmt -l .        # o workflow falha se isto imprimir qualquer coisa
go vet ./...
go test -race ./...
go build ./...

Rode esses quatro antes de abrir um pull request e você terá reproduzido o CI exatamente. -race não é decoração: o escritor de SSE tem dois escritores por construção, o turno e o heartbeat, e uma escrita intercalada corromperia um frame que o cliente está no meio de interpretar.

release.yml constrói e publica a imagem em um push para main ou em uma tag, com o cache de camadas desativado para que os testes dentro do Dockerfile rodem de verdade para aqueles bytes.

crab-shell-proxy

Não há workflow de pull request nenhum. O único workflow do repositório, release-image.yml, constrói e publica a imagem em um push para main ou em uma tag de versão — e o gate vive dentro do Dockerfile, que roda go vet ./... e go test ./... antes da etapa de build. Um teste vermelho significa nenhuma imagem.

Localmente, esses dois comandos são a verificação inteira:

go vet ./... && go test ./...

Uma segunda suíte dirige um daemon Docker real e fica atrás de uma build tag, então ela não roda nem no comando acima nem no build da imagem. Rode-a quando você tiver mudado o cliente da Engine API ou qualquer coisa sobre a criação de containers:

go test -tags integration ./internal/docker -run TestIntegration -v

Ela cria e remove um container Alpine descartável, então precisa de um /var/run/docker.sock alcançável, mas de nenhuma chave de LLM.

crab-exoskeleton-webapp

Dois workflows, e nenhum roda os testes. mycelium-transport.yml passa um grep em app/ e lib/ nos pull requests que os tocam, quebrando o build quando uma nova chamada REST ao gateway mycelium aparece fora da sua lista de permissões — veja o capítulo do componente para saber o que é essa regra e por quê. release-image.yml constrói e publica a imagem em um push para main ou em uma tag, o que roda yarn install --frozen-lockfile e depois yarn build.

Então a verificação efetiva do CI sobre o código é: ele compila. A suíte de testes é real e extensa, está documentada no README do repositório, e rodá-la é com você:

yarn install
yarn test        # Vitest
yarn build       # a mesma coisa que o build da imagem roda

Não rode yarn lint. O script é next lint, mas o ESLint não é uma dependência deste repositório — ele não está nem em package.json nem em yarn.lock e não está instalado, então o script não consegue fazer nada. É um resquício de um scaffold.

Também não há script de verificação de tipos. tsconfig.json define noEmit, então o TypeScript é um verificador em vez de uma etapa de build, e os erros de tipo chegam até você através de yarn build e do seu editor.

harness-sphere

Nenhum workflow roda cargo test, e nenhum roda cargo clippy. O que o CI roda é cargo audit --deny warnings quando um Cargo.toml ou um Cargo.lock muda, semanalmente por agendamento e sob dispatch manual; um comentário de revisão automatizado escrito por modelo em cada pull request; e o build da imagem, cujo Dockerfile compila o binário de release sem rodar a suíte.

Os testes existem, sob crates/runtime/tests/ e harnesssphere/tests/, e rust-toolchain.toml pede rustfmt e clippy junto com o Rust stable. Nada vai rodá-los por você, então rode você mesmo:

cargo build --release
cargo test

A feature otlp é a única que o binário declara; um build que vai enviar métricas para um collector quer cargo build --release --features otlp.

Trabalhando neste livro

O livro é um mdBook sob docs/book/, com a fonte em inglês em src/ e a tradução em português gerada a partir de po/pt-BR.po. O inglês é a fonte e o português é uma tradução: traduzir significa editar o catálogo, nunca escrever uma segunda árvore de arquivos Markdown que pode divergir da primeira.

cd docs/book
mdbook build                                           # o livro em inglês
MDBOOK_BOOK__LANGUAGE=pt-BR mdbook build --dest-dir book/pt-BR

O build em português precisa do mdbook-gettext, que vem do mdbook-i18n-helpers. .github/workflows/deploy-docs.yml constrói os dois em um push para main que toca docs/book/** e os publica no GitHub Pages, com o livro em português aninhado dentro do em inglês para que um único artefato carregue os dois.

Dê ao build em português um destino próprio, como acima: book.toml define build-dir = "book", então um mdbook build simples em português sobrescreveria o livro em inglês no lugar. Note também que create-missing = false está definido, então um capítulo listado em SUMMARY.md sem arquivo em disco quebra o build em vez de ser criado vazio.

Para onde ir agora

Contribuindo cobre as convenções que uma mudança precisa seguir, incluindo a cadeia de submódulos e como uma mudança se move por ela. Solução de problemas cobre as falhas que as pessoas de fato encontram rodando a stack.