A CLI do Zero: check, run, build, test, fix e explain

O que a CLI te dá

O binário zero é a toolchain de desenvolvimento inteira. Não há gerenciador de pacotes, formatador, linter ou test runner separados — todos são subcomandos do zero. Isso mantém a superfície pequena e previsível, que é o objetivo.

Um menu curto dos comandos que você vai tocar mais:

Comando	O que faz
zero check	Verifica tipos do código-fonte sem produzir executável.
zero run	Compila e roda em um passo.
zero build	Compila para um executável nativo.
zero test	Roda os alvos de teste de um pacote.
zero fix	Aplica ou pré-visualiza planos de reparo estruturados.
zero explain	Busca a explicação em prosa de um código de diagnóstico.
zero new	Cria a estrutura de um pacote novo.
zero --version	Imprime a versão da toolchain.

Cada um aceita --json para emitir saída legível por máquina em vez de texto formatado para humanos.

zero check

O cavalo de batalha. zero check roda as verificações estáticas do compilador — parsing, verificação de tipos, inferência de capacidades e efeitos, detecção de imports faltantes — e para antes da geração de código. É rápido, o que importa porque agentes e editores chamam constantemente.

zero check hello.0

Saída limpa (nada impresso, exit 0) significa que o arquivo está bem formado. Erros saem como texto legível para humanos por padrão. Adicione --json e você ganha a forma estruturada que os agentes consomem:

zero check hello.0 --json

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

A forma do diagnóstico está totalmente documentada em Diagnósticos em JSON. Note o campo code estável — NAM003 sempre significa "identificador desconhecido", independente da versão do compilador.

Você também pode apontar o check para um diretório de pacote em vez de um único arquivo:

zero check ./my-package

Ele lê zero.json, percorre a árvore de fontes e reporta todo problema em todo alvo.

zero run

run compila e executa em um passo. Melhor quando você está iterando num programa pequeno e não se importa com produzir um binário no disco.

zero run hello.0

Equivale a rodar zero build e depois invocar o binário produzido, só que o artefato é descartado. A saída padrão do seu programa é encaminhada para o stdout do terminal — as chamadas world.out.write do programa aterrissam na sua tela.

Se o seu programa precisa de argumentos, passe depois de um --:

zero run greet.0 -- Alice

O runtime dá ao programa acesso a esses argumentos através da mesma capacidade World que expõe o I/O.

zero build

Quando quiser um artefato, use build:

zero build hello.0

O compilador produz um executável nativo ao lado do seu arquivo-fonte (ou dentro do diretório de build do pacote, se você estiver trabalhando num pacote). Você pode rodá-lo como qualquer outro programa — nenhum runtime separado é necessário porque os binários Zero são autocontidos.

Binários Zero são pequenos. A meta de design do projeto é executáveis abaixo de 10 KB para programas triviais, alcançada pulando a toolchain LLVM e emitindo caminhos de código compactos diretamente.

zero test

Rodar os alvos de teste de um pacote:

zero test

Testes ficam junto ao código-fonte em src/, declarados como alvos de teste no zero.json do pacote. O runner descobre, executa cada um e emite pass/fail. Com --json, a saída é estruturada por teste — nome, status, duração, diagnósticos capturados — para agentes e ferramentas de CI.

Pacotes Zero cobre como declarar alvos de teste no zero.json.

zero fix

fix consome os metadados de reparo que o check --json produz. Tem dois modos:

zero fix --plan --json   # mostra o plano estruturado, não aplica
zero fix                 # aplica o plano direto

Um plano se parece com algo assim (a forma é ilustrativa):

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

A ideia é que um agente busque o plano, decida se confia e aplique direto ou entregue a um passo de raciocínio mais alto. Planos são dados; agentes não precisam interpretar prosa para agir.

zero explain

explain é o lado em prosa do sistema de diagnósticos:

zero explain NAM003

Imprime uma explicação legível para humanos do código de erro — o que significa, por que o compilador emite e como costumam ser as correções. Útil quando:

• Um humano está depurando e quer uma resposta mais longa do que a mensagem inline.
• Um agente esbarra num código que não estava nos dados de treinamento e quer mais contexto.

O próprio código é estável entre versões do compilador, então explicações em cache continuam válidas.

zero new

Esqueletizar um pacote novo:

zero new cli hello

Isso cria um diretório hello/ com um manifesto zero.json e um src/main.0 inicial. O primeiro argumento (cli aqui) escolhe um template — um aplicativo de linha de comando executável neste caso. Pacotes Zero explica o layout em detalhe.

O hábito do --json

Quase todo comando suporta --json. Se você está construindo ferramentas, um arcabouço de agente ou um pipeline de CI em volta do Zero, use a forma JSON como padrão. Ela é:

• Estável. O schema é versionado e o time o trata como contrato.
• Completa. Você ganha campos que não estão na saída para humanos (spans precisos, IDs de plano de reparo, dados do grafo de dependências).
• Parseável. Sem regex sobre prosa em inglês para extrair um número de linha.

Para humanos, deixe o --json de fora — o texto formatado é o que você quer no terminal.

Outros comandos úteis

Alguns comandos menos frequentes que vale conhecer:

• zero graph --json — emite o grafo de dependências de um pacote como dado estruturado. Útil para entender o que depende do quê, e para agentes que querem raciocinar sobre pontos de chamada.
• zero size --json — relata o tamanho em disco dos artefatos compilados, dividido por alvo. Útil quando você se importa com a pegada do binário (que é uma meta de design do Zero).
• zero --version — imprime a versão da toolchain. Anote isso em algum lugar se trabalha em time — Zero é pré-1.0 e mudanças incompatíveis acontecem.

A seguir: pacotes Zero

Um único arquivo .0 é suficiente para um hello-world. Projetos reais usam pacotes com um manifesto zero.json e um diretório src/. Pacotes Zero mostra como esqueletizar um e explica cada campo.