La CLI de Zero: check, run, build, test, fix y explain

Qué te da la CLI

El binario zero es toda la cadena de herramientas de desarrollo. No hay un gestor de paquetes aparte, ni un formateador, ni un linter, ni un runner de tests: todos son subcomandos de zero. Eso mantiene la superficie pequeña y predecible, que es el objetivo.

Un menú corto de los comandos que más vas a tocar:

Comando	Qué hace
zero check	Chequea tipos del código sin producir un ejecutable.
zero run	Compila y ejecuta en un solo paso.
zero build	Compila a un ejecutable nativo.
zero test	Ejecuta los destinos de test de un paquete.
zero fix	Aplica o previsualiza planes de reparación estructurados.
zero explain	Busca la explicación en prosa de un código de diagnóstico.
zero new	Genera un paquete nuevo a partir de una plantilla.
zero --version	Imprime la versión del toolchain.

Cada uno de ellos acepta --json para emitir salida legible por máquinas en lugar de texto formateado para humanos.

zero check

El caballo de batalla. zero check ejecuta los chequeos estáticos del compilador — parseo, chequeo de tipos, inferencia de capacidades y efectos, detección de imports faltantes — y se detiene antes de la generación de código. Es rápido, lo cual importa porque agentes y editores lo invocan constantemente.

zero check hello.0

Una salida limpia (nada impreso, exit 0) significa que el archivo está bien formado. Por defecto los errores salen como texto legible. Añade --json y obtienes la forma estructurada que consumen los agentes:

zero check hello.0 --json

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

La forma del diagnóstico está documentada por completo en Diagnósticos JSON. Fíjate en el campo code estable: NAM003 siempre significa "identificador desconocido", sin importar la versión del compilador.

También puedes apuntar check a un directorio de paquete en lugar de a un solo archivo:

zero check ./mi-paquete

Lee zero.json, recorre el árbol de fuentes y reporta cada problema en cada destino.

zero run

run compila y ejecuta en un solo paso. Es lo mejor cuando estás iterando sobre un programa pequeño y no te importa producir un binario en disco.

zero run hello.0

Equivale a ejecutar zero build y luego invocar el binario producido, salvo que el artefacto se descarta. El stdout de tu programa se reenvía al stdout de tu terminal: las llamadas world.out.write del programa aterrizan en tu pantalla.

Si tu programa necesita argumentos, pásalos después de un --:

zero run greet.0 -- Alice

El runtime le da al programa acceso a esos argumentos a través de la misma capacidad World que expone la E/S.

zero build

Cuando quieres un artefacto, usa build:

zero build hello.0

El compilador produce un ejecutable nativo junto al archivo fuente (o bajo el directorio de build del paquete si trabajas dentro de uno). Puedes ejecutarlo como cualquier otro programa: no hace falta un runtime aparte porque los binarios de Zero son autocontenidos.

Los binarios de Zero son pequeños. El objetivo de diseño del proyecto son ejecutables de menos de 10 KB para programas triviales, logrado al saltarse el toolchain de LLVM y emitir rutas de código compactas directamente.

zero test

Ejecuta los destinos de test de un paquete:

zero test

Los tests viven junto al código fuente bajo src/, declarados como destinos de test en el zero.json del paquete. El runner los descubre, ejecuta cada uno y emite pass/fail. Con --json, la salida es estructurada por test — nombre, estado, duración, diagnósticos capturados — para agentes y herramientas de CI.

Paquetes de Zero cubre cómo declarar destinos de test en zero.json.

zero fix

fix consume los metadatos de reparación que produce check --json. Tiene dos modos:

zero fix --plan --json   # muestra el plan estructurado, no lo aplica
zero fix                 # aplica el plan in situ

Un plan tiene esta pinta (la forma es ilustrativa):

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

La idea es que un agente recoja el plan, decida si confiar en él y o bien lo aplique directamente o lo pase a una capa de razonamiento superior. Los planes son datos; los agentes no tienen que interpretar prosa para actuar.

zero explain

explain es la cara en prosa del sistema de diagnósticos:

zero explain NAM003

Imprime una explicación legible del código de error: qué significa, por qué el compilador lo emite, cómo suelen ser los arreglos típicos. Útil cuando:

• Una persona está depurando y quiere una respuesta más larga que el mensaje en línea.
• Un agente se topa con un código de diagnóstico que no estaba en sus datos de entrenamiento y quiere más contexto.

El código en sí es estable entre versiones del compilador, así que las explicaciones cacheadas siguen siendo válidas.

zero new

Genera un paquete nuevo a partir de una plantilla:

zero new cli hello

Eso crea un directorio hello/ con un manifest zero.json y un src/main.0 inicial. El primer argumento (cli aquí) elige una plantilla — una aplicación de línea de comandos ejecutable en este caso. Paquetes de Zero explica el layout en detalle.

El hábito de --json

Prácticamente todos los comandos soportan --json. Si estás construyendo tooling, un harness para un agente o un pipeline de CI alrededor de Zero, ten el formato JSON como predeterminado. Es:

• Estable. El esquema está versionado y el equipo lo trata como un contrato.
• Completo. Recibes campos que no aparecen en la salida humana (rangos precisos, IDs de planes de reparación, datos del grafo de dependencias).
• Parseable. Sin regex sobre prosa para sacar un número de línea.

Para humanos, deja --json desactivado: el texto formateado es lo que quieres en una terminal.

Otros comandos útiles

Unos cuantos comandos menos frecuentes pero que conviene conocer:

• zero graph --json — emite el grafo de dependencias de un paquete como datos estructurados. Útil para entender qué depende de qué y para agentes que quieren razonar sobre los sitios de llamada.
• zero size --json — reporta el tamaño en disco de los artefactos compilados, desglosado por destino. Útil cuando te importa el tamaño del binario (que es un objetivo de diseño de Zero).
• zero --version — imprime la versión del toolchain. Fíjala en algún sitio si trabajas en equipo: Zero es pre-1.0 y sí caen cambios incompatibles.

Lo siguiente: paquetes de Zero

Un único archivo .0 está bien para un hola mundo. Los proyectos reales usan paquetes con un manifest zero.json y un directorio src/. Paquetes de Zero muestra cómo crear uno y explica cada campo.