# Arquitetura interna da CLI
Dispatcher Zig, configuração, servidores, compilação, HMR, ownership e testes de contribuição.
## Percurso de uma invocação
O launcher npm identifica a plataforma e executa o binário. `main.zig` recebe os argumentos e despacha o primeiro token para um módulo de comando. Cada comando decide como interpretar o restante: por isso não existe uma gramática global uniforme de flags.
Os comandos de projeto obtêm uma estrutura `WuConfig` do loader. Essa configuração mantém suas strings em uma arena própria e expõe `deinit` para liberar a memória. O mecanismo evita retornar visualizações de um buffer JSON já liberado. A descoberta é uma fonte alternativa de configuração, não uma etapa que sempre se combina com um arquivo explícito.
## Mapa de módulos
| Caminho de origem | Responsabilidade |
| --- | --- |
| `src/main.zig` | Dispatcher, versão e agregador de testes Zig |
| `src/cli/` | Ajuda, banner, modo de terminal, menus e prompts |
| `src/config/config.zig` | Parsing e gravação da configuração |
| `src/config/discovery.zig` | Heurísticas de projetos em subdiretórios |
| `src/config/deps.zig` | Consumo de aliases e toolchains locais |
| `src/commands/` | Casos de uso e geração de artefatos |
| `src/runtime/dev_server.zig` | Listener, rotas, módulos e ponte de recarga |
| `src/runtime/compile.zig` | Seleção do compilador e conexão com o daemon |
| `src/runtime/compiler_daemon.js` | Compiladores Node e delimitação de mensagens |
| `src/runtime/transform.zig` | Reescrita de imports, aliases e CSS |
| `src/runtime/hypervisor/` | Watcher e router por prefixos |
| `src/runtime/security.zig` | Validação de caminhos e política HTTP |
| `src/orchestrator/` | Processos de desenvolvimento Vite e supervisão |
| `src/util/jobobject.zig` | Ciclo de vida de processos filhos no Windows |
A presença de `src/proxy/server.zig` ou `src/commands/test.zig` não demonstra que sejam o caminho ativo de um comando. Para determinar isso, comece no dispatcher e siga as chamadas, em vez de deduzir capacidades pelos nomes dos arquivos.
`src/runtime/dev/` separa rotas, arquivos, imports, CSS, ambiente, sockets e HMR. `module_graph.zig` mantém identidade e resolução por importador; `project_fs.zig` contém os acessos a arquivos. `catalog.zig`, `semver.zig` e `json_doc.zig` concentram versões, interseções e escrita de manifestos. `deploy.zig` e `build_cache.zig` implementam substituição transacional da saída local e reutilização do build.
## Servidor e compilador
Uma solicitação chega por HTTP, é validada, atribuída a uma app ou ao shell e resolvida para um arquivo ou dependência. A compilação produz JavaScript; depois os imports são ajustados às URLs do servidor. A identidade da app deve acompanhar todo o percurso para resolver suas dependências, estilos e toolchain.
O daemon mantém um canal por pipes. As solicitações carregam um identificador, tipo de compilação, arquivo, loader, comprimento e diretório da app. A resposta repete o identificador e transmite código ou erro. Os comprimentos delimitam o conteúdo; os erros são reduzidos a uma única linha de protocolo.
O protocolo multiplexa solicitações por identificador. `compile_pool.zig` gerencia vários daemons com prazos e `compile_warmup.zig` antecipa imports; Angular reutiliza seu compilador incremental. O VFS, o pool de transformações anterior e o transformador JSX nativo desativado foram removidos.
A saída padrão do daemon pertence ao protocolo. Mensagens acidentais de um plugin podem desalinhá-lo; o daemon redireciona vários níveis de `console` para seu log. O processo pai verifica o identificador da resposta e reinicia uma conversa desalinhada.
## Watcher e router
O hypervisor registra os prefixos das apps em um roteador e observa diretórios do projeto. Integra mecanismos de eventos de arquivo e caches de conteúdo. Seu ownership exige atenção: ao retornar o servidor por valor, os ponteiros para campos internos devem ser vinculados à localização final. Existe `bindRunning` para essa relação de ciclo de vida.
O servidor coordena a parada, o fechamento das conexões e o daemon. No Windows, Job Objects ajudam a impedir que processos filhos sobrevivam ao processo proprietário. Essa funcionalidade exige testes no sistema operacional real; inspecionar código não equivale a observar a limpeza de processos em todas as plataformas.
## Construir e testar uma alteração
```bash
zig build
zig build test --summary all
npm test
```
`build.zig` define as etapas de compilação e os testes Zig. `npm test` executa as invariantes de `scripts/check-invariants.mjs` e os arquivos `tests/*.test.cjs`, que verificam o launcher, o protocolo do daemon e contratos como a saída do doctor. Execute os testes contra o binário que acabou de construir. O resumo permite verificar quantos casos foram executados e quais foram omitidos; os testes de navegador continuam necessários para validar as apps geradas.
`main.zig` importa explicitamente os módulos com testes; invariantes verificam o agregador e a referência de comandos. `npm run test:fuzz` exercita parsers de HTTP, WebSocket, caminhos, JSON, SemVer e imports. Releases usam ReleaseSafe, checksums e recompilações reproduzíveis.
Para mudanças de protocolo, convém testar mensagens fragmentadas, várias solicitações em um chunk, erros longos e identificadores trocados. Para mudanças de scaffold, é necessário gerar, compilar e montar no navegador. Para mudanças de HTTP, devem ser testadas rotas, métodos, assets ausentes e cabeçalhos da resposta final.
## Referência de implementação
- `wu-cli/src/main.zig`
- `wu-cli/src/runtime/dev/`
- `wu-cli/src/runtime/compile_pool.zig`
- `wu-cli/src/runtime/compiler_daemon.js`
- `wu-cli/src/runtime/module_graph.zig`
- `wu-cli/src/runtime/project_fs.zig`
- `wu-cli/src/commands/deploy.zig`
- `wu-cli/scripts/check-invariants.mjs`
- `wu-cli/src/fuzz.zig`