Desenvolvimento

Requisitos

• A versão do Go declarada em go.mod para comandos diretos de desenvolvimento. ./install.sh inicializa temporariamente a toolchain exata revisada quando o Go estiver ausente ou for muito antigo.
• Git
• Bash e ShellCheck
• Python 3 para empacotamento determinístico da Web skill
• Docker apenas para testes de integração das dependências do servidor

Para um checkout privado, autentique o Git e clone por SSH:

git clone git@github.com:ivo-lopes/ivoai.git
cd ivoai
./install.sh
ivoai setup

Verificações locais

scripts/test-managed-opencode.sh usa o artefato OpenCode pinado com fixtures locais de provider e MCP. A matriz cobre descoberta e execução nativa pelo mesmo frontend/bridge, HTTP/SSE, permissões, attach, teclado e resize real, sem exigir credenciais pessoais de providers.

node --test internal/opencodebridge/presentation.test.mjs compara goldens determinísticos das funções de apresentação importadas pela TUI: identidade, permissões, autenticação/quota, runtime, servidores, seleção restrita, degradação e linhas em 60/100/160 colunas. Goldens em Go cobrem metadados dos seletores de modelo/variant e erros sanitizados. Testes normais nunca regravam os baselines. Após revisar uma mudança intencional, use UPDATE_GOLDENS=1 nos testes correspondentes; a CI recusa esse modo. Timestamps, portas e IDs de sessão não entram na apresentação. Estado, modelo, reasoning, permissões, health e seleção nunca são normalizados.

gofmt -w .
go test ./...
go test -race ./...
go vet ./...
shellcheck install.sh scripts/*.sh
scripts/install-smoke.sh
scripts/upgrade-matrix.sh
scripts/package-skill.sh
unzip -t dist/ivoai-memory-context.zip
go build ./cmd/ivoai
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build ./cmd/ivoai
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build ./cmd/ivoai

A CI também executa govulncheck ./.... Os testes usam diretórios XDG temporários, processos executáveis falsos e servidores httptest. Eles não acessam credenciais de desenvolvedor do Codex ou do Claude. Os packages do servidor continuam testáveis sem root, systemd, Docker ou um processo Qdrant ativo.

O harness do scheduler automático usa adapters falsos do Codex/Claude, controle de ciclo de vida falso do Ruflo e registros sintéticos de cotas/capabilities. Seu teste de DAG temporal executa simultaneamente dois workers independentes com atraso e verifica que tarefas dependentes não comecem antecipadamente. Os testes de roteamento cobrem os quatro níveis de pontuação, pesos normalizados, esgotamento de cota por provider/modelo, pressão de cota, esforço incompatível, capabilities indisponíveis, rejeição de trabalho duplicado e seleção econômica entre primary e worker. Nenhum teste normal invoca um LLM real.

O harness de atualização constrói a tag v0.5.0 real e o candidato atual. Um helper vinculado dentro do módulo v0.5.0 arquivado executa download, verificação de checksum, extração, sondagem de versão e promoção atômica reais do updater publicado contra um servidor local de releases. Em seguida, o candidato executa setup/Doctor e seu update --rollback real e compatível com o legado; o harness valida a leitura da v0.5.0, a preservação de campos desconhecidos e marcadores pertencentes aos providers e a atualização após o rollback. O mesmo harness repete a promoção histórica, a bridge de setup simples, o rollback, o Doctor do servidor antigo e a atualização após rollback em uma instalação somente servidor; ele também verifica que a bridge não crie configuração de cliente. Testes unitários de transação cobrem o novo updater com journal, modo servidor e migração injetada, Doctor, interrupção e falhas de tamanho, disco, caminho e ownership. A CI faz checkout de todo o histórico para que a tag histórica esteja disponível.

Cobertura da instalação na CI

O job install-smoke executa em containers Ubuntu 22.04, Ubuntu 24.04 e Debian 12. O scripts/install-smoke.sh isola HOME e todos os diretórios XDG, habilita IVOAI_TEST_MODE e verifica duas execuções do instalador, duas execuções do setup do cliente, duas do setup do servidor, saída de status e doctor, estabilidade de ownership, permissões e idempotência. O modo de teste usa fixtures locais de componentes e ignora o provisionamento de Docker/systemd; portanto, esse job valida o contrato da CLI e do sistema de arquivos sem contatar contas de usuário nem hosts de componentes upstream.

O job real-client-install usa a mesma matriz de três distribuições sem IVOAI_TEST_MODE. Ele instala o binário ivoai a partir do código-fonte em checkout, executa duas vezes o setup dos componentes reais e fixados do cliente como usuário de teste sem privilégios e então verifica status, saída do doctor legível por pessoas e saída JSON do doctor. Ele não autentica contas reais do ChatGPT, Claude ou servidor ivoai e não exercita o arquivo público da release do GitHub, pois o binário ivoai vem do checkout.

O job real-server-deployment executa em um host Ubuntu 24.04. Ele instala o binário ivoai em checkout, provisiona duas vezes o servidor Docker/systemd, executa server doctor, cria um código de enrollment de curta duração e exercita backup e restauração. Essa verificação de implantação não consome o código de enrollment em um cliente separado nem usa credenciais do proprietário.

O job cross-build compila o binário para Linux amd64 e arm64. Juntos, esses jobs complementam os testes unitários, de race, vet, formatação, ShellCheck, build e vulnerabilidades do job quality.

Release

Tags de versionamento semântico acionam o workflow de release. Ele verifica os gates de qualidade, constrói arquivos para Linux amd64 e arm64, empacota a Web skill ivoai-memory-context, verifica o ZIP, gera checksums.txt para cada artefato e publica uma release no GitHub. O script de empacotamento grava metadados ZIP fixos para que uma entrada idêntica da skill produza um arquivo idêntico. Não crie uma tag em um commit antes que verificações unitárias, de race, vet, cross-build, idempotência de instalação, implantação e segurança sejam aprovadas.

Custo e origem das evidências de validação P1/P2

No backlog de 2026-10-12, use GOMAXPROCS=2, go test -p 1 e TMPDIR em disco em hosts limitados. Não execute várias suítes completas ou builds do frontend simultaneamente. As camadas têm finalidades distintas:

Camada	Escopo e custo	Acesso a provedores
Go focado	Perfis, propriedade/reparo de hooks, continuidade, replay e status; segundos a dezenas de segundos	Somente fixtures
Node e Python	Streaming limitado, reconexão, teclado e saída consumida; segundos	Nenhum
Go completo / race / vet	Configuração, sessões e ciclo de vida compartilhados; minutos, maior RAM com race	Fixtures; testes reais são opt-in
Scripts OpenCode/Codex	Binários revisados reais e contratos HTTP/TUI; minutos	Provedor local simulado, sem login
TestLiveNativeAUTOArtifact	Inferência Codex e continuidade no terminal; minutos e quota da conta	Somente Codex; estado isolado sem componente Claude
Instalação e atualização	HOME/XDG sintéticos, componentes e recuperação de estado	Fixtures locais, sem migração de produção

O smoke real aceita IVOAI_NATIVE_SMOKE_CONTINUITY=1 e, com IVOAI_NATIVE_SMOKE_FRONTEND=codex, IVOAI_NATIVE_SMOKE_SWITCH=1. Esta última opção verifica interrupção e reabertura do frontend ocioso e troca para OpenCode sem mudar o provedor. Isso não comprova recuperação de DAG aprovado interrompido. Utilize apenas artefatos revisados e verificados por checksum nos overrides IVOAI_NATIVE_SMOKE_CODEX_PATH/IVOAI_NATIVE_SMOKE_OPENCODE_PATH. Credenciais e configurações pessoais não são copiadas. Um digest antes/depois protege a configuração pessoal do Codex.

A homologação relaciona-se à IVOAI-136 existente; o aceite de capacidades públicas segue IVOAI-135/146. Fixtures não substituem homologação com provedor, e rollback de executáveis não equivale a rollback de migração de banco.

IVOAI_NATIVE_SMOKE_RECOVERY=1 habilita separadamente o smoke real de interrupção e recuperação de execução aprovada somente leitura. Aguarda checkpoint do host com uma tarefa concluída e outra pendente, interrompe apenas o frontend próprio com PID verificado, executa session recover, exige nova aprovação e verifica integração, preservação das tarefas, repositório inalterado e identidade do provedor. Exige Linux com pidfd e janela real de interrupção; ausência de evidência falha sem editar checkpoints.