# Arquitectura interna de la CLI
Dispatcher Zig, configuración, servidores, compilación, HMR, ownership y pruebas de contribución.
## Recorrido de una invocación
El launcher npm identifica plataforma y ejecuta el binario. `main.zig` recibe los argumentos y despacha el primer token hacia un módulo de comando. Cada comando decide cómo interpretar el resto: por eso no existe una gramática global uniforme de flags.
Los comandos de proyecto obtienen una estructura `WuConfig` del loader. Esa configuración conserva sus strings en una arena propia y expone `deinit` para liberar su memoria. El mecanismo evita devolver vistas sobre el buffer JSON ya liberado. El descubrimiento es una fuente alternativa de configuración, no un paso que se mezcle siempre con un archivo explícito.
## Mapa de módulos
| Ruta de origen | Responsabilidad |
| --- | --- |
| `src/main.zig` | Dispatcher, versión y agregador de tests Zig |
| `src/cli/` | Ayuda, banner, modo terminal, menús y prompts |
| `src/config/config.zig` | Parseo y escritura de configuración |
| `src/config/discovery.zig` | Heurísticas de proyectos en subdirectorios |
| `src/config/deps.zig` | Consumo de aliases y toolchains locales |
| `src/commands/` | Casos de uso y generación de artefactos |
| `src/runtime/dev_server.zig` | Listener, rutas, módulos y puente de recarga |
| `src/runtime/compile.zig` | Selección de compilador y conexión al daemon |
| `src/runtime/compiler_daemon.js` | Compiladores Node y framing de mensajes |
| `src/runtime/transform.zig` | Reescritura de imports, alias y CSS |
| `src/runtime/hypervisor/` | Watcher y router por prefijos |
| `src/runtime/security.zig` | Validación de paths y política HTTP |
| `src/orchestrator/` | Procesos de desarrollo Vite y supervisión |
| `src/util/jobobject.zig` | Ciclo de vida de procesos hijos en Windows |
La presencia de `src/proxy/server.zig` o `src/commands/test.zig` no demuestra que sean la ruta activa de un comando. Para determinarlo empieza en el dispatcher y sigue llamadas, en lugar de deducir capacidades por nombres de archivos.
`src/runtime/dev/` separa rutas, archivos, imports, CSS, entorno, sockets y HMR. `module_graph.zig` mantiene identidad y resolución por importador; `project_fs.zig` contiene accesos a archivos. `catalog.zig`, `semver.zig` y `json_doc.zig` concentran versiones, intersecciones y escritura de manifiestos. `deploy.zig` y `build_cache.zig` implementan publicación local transaccional y reutilización del build.
## Servidor y compilador
Una solicitud entra por HTTP, se valida, se asigna a una app o al shell y se resuelve a archivo o dependencia. La compilación produce JavaScript; después se ajustan imports a las URLs del servidor. La identidad de la app debe acompañar todo el recorrido para resolver sus dependencias, estilos y toolchain.
El daemon mantiene un canal por pipes. Las peticiones llevan un identificador, tipo de compilación, archivo, loader, longitud y directorio de app. La respuesta repite el identificador y transmite código o error. Las longitudes enmarcan el contenido; los errores se reducen a una sola línea de protocolo.
El protocolo multiplexa peticiones por identificador. `compile_pool.zig` mantiene varios daemons con deadlines y `compile_warmup.zig` anticipa imports; Angular reutiliza su compilador incremental. El VFS, el pool de transformaciones anterior y el transformador JSX nativo desactivado se eliminaron.
La salida estándar del daemon pertenece al protocolo. Mensajes accidentales de un plugin pueden desalinearlo; el daemon redirige varios niveles de `console` a su log. El padre comprueba el identificador de respuesta y reinicia una conversación desalineada.
## Watcher y router
El hypervisor registra los prefijos de apps en un router y observa directorios del proyecto. Integra mecanismos de eventos de archivo y cachés de contenido. Su ownership requiere atención: al devolver el servidor por valor, los punteros a campos internos deben enlazarse con la ubicación final. Existe `bindRunning` para esa relación de ciclo de vida.
El servidor coordina la detención, el cierre de conexiones y el daemon. En Windows, Job Objects ayudan a que procesos hijos no sobrevivan al proceso propietario. Esa funcionalidad requiere pruebas del sistema operativo real; inspeccionar código no equivale a observar la limpieza de procesos en todas las plataformas.
## Construir y probar una modificación
```bash
zig build
zig build test --summary all
npm test
```
`build.zig` define los pasos de compilación y pruebas Zig. `npm test` ejecuta las invariantes de `scripts/check-invariants.mjs` y los archivos `tests/*.test.cjs`, que comprueban el launcher, el protocolo del daemon y contratos como la salida de doctor. Ejecuta las pruebas contra el binario que acabas de construir. El resumen permite comprobar cuántos casos corrieron y cuáles se omitieron; las pruebas de navegador siguen siendo necesarias para validar las apps generadas.
`main.zig` importa explícitamente los módulos con tests; las invariantes comprueban el agregador y la referencia de comandos. `npm run test:fuzz` ejercita parsers de HTTP, WebSocket, rutas, JSON, SemVer e imports. La release usa ReleaseSafe, checksums y reconstrucciones reproducibles.
Para cambios de protocolo conviene probar mensajes fragmentados, múltiples peticiones en un chunk, errores largos e identificadores cruzados. Para cambios de scaffold se necesita generar, compilar y montar en navegador. Para cambios de HTTP se deben probar rutas, métodos, assets ausentes y cabeceras de la respuesta final.
## Referencia de implementación
- `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`