zuke-build/zuke

Configurar Zuke en un proyecto

Zuke define las compilaciones como una clase de TypeScript que se ejecuta en Deno. Cada objetivo es un campo de la clase; los objetivos se referencian entre sí mediante this.<campo> (nunca cadenas). Los paquetes se importan desde JSR (jsr:@zuke/...), no de npm.

La ruta rápida: zuke setup

La herramienta @zuke/cli lo prepara todo. Instálela una vez, luego ejecute setup en el proyecto de destino:

deno install -A -g -n zuke jsr:@zuke/cli   # una vez, globalmente
zuke setup                                  # en la raíz del proyecto
./zuke                                       # ejecutar la compilación

¿Sin instalación global? El mismo asistente se ejecuta directamente:

deno run -A jsr:@zuke/cli setup

Banderas de setup: --dir <ruta>, --name <NombreClase>, --force (sobrescribir archivos existentes), --yes (no interactivo), --launcher-name <nombre> (escribir el lanzador con un nombre diferente cuando un directorio zuke/ ya lo ocupa — una colisión de directorios ahora falla con un error útil en lugar de omitir silenciosamente el lanzador).

Para leer la API de un paquete @zuke/* sin el ruido de @types/node de un repositorio Node, ejecute zuke doc <paquete> (por ejemplo, zuke doc core) — ejecuta deno doc en un directorio aislado.

Migración de un proyecto existente: zuke import

Si el proyecto ya tiene scripts de package.json o un Makefile, prefiera zuke import en lugar de setup — los lee y genera un zuke.ts con un objetivo por tarea, un punto de partida funcional en lugar de una compilación vacía:

zuke import                  # detecta automáticamente package.json, luego un Makefile
zuke import --from makefile   # o fijar la fuente (package.json | makefile)

Cada script/objetivo se convierte en un target(); un comando se asigna a CmdTasks.exec(...) — un marcador de posición, no el destino: antes de aceptarlo, consulte el catálogo de paquetes (la lista ## Packages de llms.txt, o la tabla en la chuleta de zuke-write-build) para buscar un envoltorio @zuke/<herramienta> que coincida con ese comando y reemplace el marcador de posición con él — dejar CmdTasks.exec en su lugar para una herramienta que tiene un envoltorio tipado es un error, no un atajo. Una cadena && se convierte en pasos secuenciales, una delegación de run/prerrequisito se convierte en .dependsOn(...), y cualquier cosa demasiado específica de shell para traducir (tuberías, redirecciones, asignaciones de entorno) se conserva detrás de un // TODO para que el archivo siga compilando. Prepara los lanzadores y deno.json exactamente como setup, y acepta las mismas banderas --dir, --name, --force, --yes. Después, use la habilidad zuke-write-build para terminar de reemplazar cualquier llamada CmdTasks.exec generada restante con envoltorios *Tasks tipados.

Lo que escribe zuke setup

• zuke.ts — una clase de compilación inicial con un objetivo de muestra y un default.
• ./zuke + ./zuke.ps1 — lanzadores que localizan el proyecto y ejecutan zuke.ts con el Deno en PATH. Si falta Deno, señalan la documentación oficial de instalación y salen en lugar de canalizar un script de instalación a un shell, lo que descargaría y ejecutaría código no verificado. Pasan --frozen una vez que existe un deno.lock, por lo que la primera ejecución escribe el archivo de bloqueo y cada ejecución posterior lo verifica.
• deno.json — fusionado para agregar una tarea zuke, además de fmt/lint/test si están ausentes. La fusión es todo o nada: si una tarea zuke ya está declarada, el archivo se deja completamente intacto, y uno no analizable se omite con un aviso.
• zuke.json — { "name": "..." }, que marca la raíz del repositorio.
• .gitignore — creado o añadido para que se ignore .zuke/ (allí residen la caché y el estado de ejecución duradero); no se modifica si ya lo cubre.

Ejecutar la compilación

./zuke                 # ejecutar el objetivo predeterminado (Windows: .\zuke.ps1)
./zuke <objetivo>        # ejecutar un objetivo específico
./zuke --list          # listar todos los objetivos
./zuke --list --json   # toda la superficie de compilación (comandos, banderas, objetivos) como JSON
./zuke <objetivo> --dry-run   # imprimir el plan sin ejecutar

La CLI se autodescribe: ./zuke --help imprime la gramática de uso más los objetivos y parámetros activos de la compilación, por lo que un agente descubre la superficie de comandos real en lugar de adivinar. Para que un cliente de IA opere la compilación mediante llamadas tipadas, zuke mcp ejecuta un servidor de Protocolo de Contexto de Modelo sobre ella (regístrese con claude mcp add zuke -- deno run -A zuke.ts mcp; agregue --allow-run para permitir que el agente ejecute objetivos, no solo inspeccionarlos).

Si Deno ya está instalado, también puede usar deno task zuke <objetivo> o deno run -A zuke.ts <objetivo>. La bandera -A otorga permisos, ya que los objetivos típicamente ejecutan procesos y tocan archivos. Estos no son completamente equivalentes al lanzador: la tarea zuke generada omite deliberadamente --frozen, por lo que puede reparar un archivo de bloqueo obsoleto donde ./zuke fallaría.

Configuración manual (sin CLI)

Cree zuke.ts en la raíz del proyecto, extienda Build, declare objetivos con target() y llame a await run(MiBuild) al 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);

Ejecute con deno run -A zuke.ts test. (Para la experiencia del lanzador ./zuke, prefiera zuke setup, que coloca los scripts de lanzamiento por usted).

Encontrar la API exacta — nunca adivinar

Cada herramienta externa tiene un envoltorio *Tasks tipado; no recurra a Deno.Command o shell manual. Primero confirme que existe un envoltorio — el catálogo ## Packages de llms.txt o la tabla en la chuleta de zuke-write-build es la única manera de responder eso; un deno doc por paquete necesita un nombre como destino, por lo que no puede revelar que existe uno. Una vez que conozca el nombre del paquete, obtenga sus firmas exactas:

• Un solo paquete en la línea de comandos: deno doc jsr:@zuke/<paquete>. Prefiera esto en un repositorio consumidor — resuelve la versión que el proyecto realmente tiene instalada, por lo que no puede describir una API que esa versión no tenga.
• Toda la superficie tipada de cada paquete está en llms-full.txt (indexado por llms.txt) — en la raíz del repositorio dentro del propio repositorio de Zuke, o desde un repositorio consumidor https://raw.githubusercontent.com/zuke-build/zuke/master/llms-full.txt (índice: https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt). Ambos siguen master, por lo que pueden documentar símbolos que están fusionados pero aún no lanzados; úselos para encontrar lo que existe, luego confirme la firma con deno doc.

Una vez que el proyecto esté preparado, use la habilidad zuke-write-build para agregar y editar objetivos.