zuke-build/zuke

Configurar Zuke em um projeto

O Zuke define builds como uma classe TypeScript executada no Deno. Cada target é um campo da classe; targets referenciam-se mutuamente por this.<campo> (nunca strings). Pacotes são importados do JSR (jsr:@zuke/...), não do npm.

O caminho rápido: zuke setup

A ferramenta @zuke/cli scaffolding tudo. Instale-a uma vez, depois execute setup no projeto alvo:

deno install -A -g -n zuke jsr:@zuke/cli   # uma vez, globalmente
zuke setup                                  # na raiz do projeto
./zuke                                       # execute o build

Não fez instalação global? O mesmo wizard executa diretamente:

deno run -A jsr:@zuke/cli setup

Flags do setup: --dir <caminho>, --name <NomeClasse>, --force (sobrescrever arquivos existentes), --yes (não interativo), --launcher-name <nome> (escrever o launcher com outro nome quando um diretório zuke/ já ocupa esse nome — uma colisão de diretório agora falha com um erro acionável em vez de pular silenciosamente o launcher).

Para ler a API de um pacote @zuke/* sem o ruído de @types/node de um repositório Node, execute zuke doc <pacote> (ex.: zuke doc core) — ele executa deno doc em um diretório isolado.

Migrando um projeto existente: zuke import

Se o projeto já tem scripts package.json ou um Makefile, prefira zuke import ao setup — ele os lê e gera um zuke.ts com um target por tarefa, um ponto de partida funcional em vez de um build vazio:

zuke import                  # detecta automaticamente package.json, depois um Makefile
zuke import --from makefile   # ou especifique a fonte (package.json | makefile)

Cada script/target torna-se um target(); um comando mapeia para CmdTasks.exec(...) — um placeholder, não o destino: antes de aceitá-lo, verifique o catálogo de pacotes (lista ## Packages do llms.txt, ou a tabela no cheatsheet do zuke-write-build) por um wrapper @zuke/<ferramenta> que corresponda àquele comando e substitua o placeholder por ele — deixar CmdTasks.exec no lugar para uma ferramenta que tem um wrapper tipado é um bug, não um atalho. Uma cadeia de && torna-se etapas sequenciais, uma delegação de run/pré-requisito torna-se .dependsOn(...), e qualquer coisa muito específica de shell para traduzir (pipes, redirecionamentos, atribuições de env) é preservada atrás de um // TODO para que o arquivo ainda compile. Ele scaffolding os launchers e deno.json exatamente como setup, e aceita as mesmas flags --dir, --name, --force, --yes. Depois, use a habilidade zuke-write-build para finalizar substituindo quaisquer chamadas CmdTasks.exec geradas restantes por wrappers *Tasks tipados.

O que o zuke setup escreve

• zuke.ts — uma classe de build inicial com um target de exemplo e um default.
• ./zuke + ./zuke.ps1 — launchers que localizam o projeto e executam zuke.ts com o Deno no PATH. Se o Deno estiver faltando, eles apontam para a documentação oficial de instalação e saem em vez de canalizar um script de instalação para um shell, o que baixaria e executaria código não verificado. Eles passam --frozen assim que um deno.lock existe, então a primeira execução escreve o arquivo de lock e toda execução posterior o verifica.
• deno.json — mesclado para adicionar uma tarefa zuke, além de fmt/lint/test se ausentes. A mesclagem é tudo-ou-nada: se uma tarefa zuke já está declarada, o arquivo é deixado completamente intacto, e um não analisável é pulado com um aviso.
• zuke.json — { "name": "..." }, que marca a raiz do repositório.
• .gitignore — criado ou estendido para que .zuke/ seja ignorado (o cache e o estado de execução durável ficam lá); intocado se já cobrir isso.

Executando o build

./zuke                 # executa o target padrão  (Windows: .\zuke.ps1)
./zuke <target>        # executa um target específico
./zuke --list          # lista todos os targets
./zuke --list --json   # toda a superfície de build (comandos, flags, targets) como JSON
./zuke <target> --dry-run   # exibe o plano sem executar

A CLI é auto-descritiva: ./zuke --help exibe a gramática de uso mais os targets e parâmetros vivos do build, então um agente descobre a superfície real de comandos em vez de adivinhar. Para um cliente AI operar o build através de chamadas tipadas, zuke mcp executa um servidor Model Context Protocol sobre ele (registre com claude mcp add zuke -- deno run -A zuke.ts mcp; adicione --allow-run para permitir que o agente execute targets, não apenas os inspecione).

Se o Deno já estiver instalado, você também pode usar deno task zuke <target> ou deno run -A zuke.ts <target>. A flag -A concede permissões, já que targets tipicamente executam processos e tocam em arquivos. Eles não são exatamente equivalentes ao launcher: a tarefa zuke scaffoldada omite deliberadamente --frozen, então ela pode curar um lockfile desatualizado onde ./zuke falharia nele.

Configuração manual (sem CLI)

Crie zuke.ts na raiz do projeto, estenda Build, declare targets com target(), e chame await run(MyBuild) no final:

import { Build, run, target } from "jsr:@zuke/core";
import { DenoTasks } from "jsr:@zuke/deno";

class CI extends Build {
  lint = target().executes(() => DenoTasks.lint());
  test = target().dependsOn(this.lint)
    .executes(() => DenoTasks.test((s) => s.allowAll()));
  default = target().dependsOn(this.test).executes(() => {});
}

await run(CI);

Execute com deno run -A zuke.ts test. (Para a experiência do launcher ./zuke, prefira zuke setup, que coloca os scripts launcher para você.)

Encontrando a API exata — nunca adivinhe

Cada ferramenta externa tem um wrapper *Tasks tipado; não recorra ao Deno.Command ou shell artesanal. Primeiro, confirme se um wrapper existe — o catálogo ## Packages do llms.txt ou a tabela no cheatsheet do zuke-write-build é a única maneira de responder isso; um deno doc por pacote precisa de um nome alvo, então não pode revelar que um existe. Depois de saber o nome do pacote, obtenha suas assinaturas exatas:

• Um único pacote na linha de comando: deno doc jsr:@zuke/<pacote>. Prefira isso em um repositório consumidor — ele resolve a versão que o projeto realmente tem instalada, então não pode descrever uma API que essa versão não possui.
• Toda a superfície tipada de cada pacote está em llms-full.txt (indexada por llms.txt) — na raiz do repositório no próprio repositório Zuke, ou a partir de um repositório consumidor https://raw.githubusercontent.com/zuke-build/zuke/master/llms-full.txt (índice: https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt). Ambos acompanham master, então podem documentar símbolos que estão mesclados mas não lançados; use-os para descobrir o que existe, depois confirme a assinatura com deno doc.

Depois que o projeto estiver scaffoldado, use a habilidade zuke-write-build para adicionar e editar targets.