zuke-build/zuke

Configurer Zuke dans un projet

Zuke définit les builds comme une classe TypeScript exécutée sur Deno. Chaque cible est un champ de classe ; les cibles se référencent entre elles par this.<champ> (jamais de chaînes). Les packages sont importés depuis JSR (jsr:@zuke/...), pas npm.

La voie rapide : zuke setup

L'outil @zuke/cli génère toute la structure. Installez-le une fois, puis exécutez setup dans le projet cible :

deno install -A -g -n zuke jsr:@zuke/cli   # une fois, globalement
zuke setup                                  # à la racine du projet
./zuke                                       # exécuter le build

Pas d'installation globale ? Le même assistant s'exécute directement :

deno run -A jsr:@zuke/cli setup

Drapeaux setup : --dir <chemin>, --name <NomClasse>, --force (écraser les fichiers existants), --yes (non interactif), --launcher-name <nom> (écrire le lanceur sous un autre nom quand un répertoire zuke/ occupe déjà le nom — une collision de répertoire échoue maintenant avec une erreur actionnable au lieu de passer silencieusement le lanceur).

Pour lire l'API d'un package @zuke/* sans le bruit d'un @types/node d'un dépôt Node, exécutez zuke doc <package> (par ex. zuke doc core) — cela lance deno doc dans un répertoire isolé.

Migrer un projet existant : zuke import

Si le projet a déjà des scripts package.json ou un Makefile, préférez zuke import à setup — il les lit et génère un zuke.ts avec une cible par tâche, un point de départ fonctionnel au lieu d'un build vide :

zuke import                  # détecte automatiquement package.json, puis un Makefile
zuke import --from makefile   # ou spécifier la source (package.json | makefile)

Chaque script/cible devient un target() ; une commande correspond à CmdTasks.exec(...) — un espace réservé, pas la destination : avant de l'accepter, vérifiez le catalogue des packages (la liste ## Packages de llms.txt, ou le tableau dans l'antisèche de zuke-write-build) pour un wrapper @zuke/<outil> correspondant à cette commande et remplacez l'espace réservé par celui-ci — laisser CmdTasks.exec en place pour un outil qui a un wrapper typé est un bug, pas un raccourci. Une chaîne && devient des étapes séquentielles, une délégation run/prérequis devient .dependsOn(...), et tout ce qui est trop spécifique au shell pour être traduit (pipes, redirections, affectations de variables d'environnement) est conservé derrière un // TODO pour que le fichier compile toujours. Il génère les lanceurs et deno.json exactement comme setup, et prend les mêmes drapeaux --dir, --name, --force, --yes. Ensuite, utilisez le skill zuke-write-build pour finir de remplacer les appels CmdTasks.exec générés restants par des wrappers *Tasks typés.

Ce que zuke setup écrit

• zuke.ts — une classe de build de démarrage avec une cible exemple et une default.
• ./zuke + ./zuke.ps1 — des lanceurs qui localisent le projet et exécutent zuke.ts avec le Deno présent dans le PATH. Si Deno est manquant, ils pointent vers la documentation officielle d'installation et se terminent plutôt que d'envoyer un script d'installation dans un shell, ce qui téléchargerait et exécuterait du code non vérifié. Ils passent --frozen une fois qu'un deno.lock existe, donc la première exécution écrit le fichier de verrouillage et chaque exécution suivante le vérifie.
• deno.json — fusionné pour ajouter une tâche zuke, ainsi que fmt/lint/test si absents. La fusion est tout-ou-rien : si une tâche zuke est déjà déclarée, le fichier est laissé complètement intact, et un fichier non analysable est ignoré avec un avertissement.
• zuke.json — { "name" : "..." }, qui marque la racine du dépôt.
• .gitignore — créé ou complété pour que .zuke/ soit ignoré (le cache et l'état d'exécution durable y résident) ; non modifié s'il le couvre déjà.

Exécution du build

./zuke                 # exécute la cible par défaut  (Windows : .\zuke.ps1)
./zuke <cible>        # exécute une cible spécifique
./zuke --list          # liste toutes les cibles
./zuke --list --json   # toute la surface du build (commandes, drapeaux, cibles) en JSON
./zuke <cible> --dry-run   # affiche le plan sans exécuter

Le CLI est auto-descriptif : ./zuke --help affiche la grammaire d'utilisation ainsi que les cibles et paramètres actifs du build, de sorte qu'un agent découvre la véritable surface de commande au lieu de deviner. Pour qu'un client IA pilote le build via des appels typés, zuke mcp exécute un serveur Model Context Protocol dessus (enregistrer avec claude mcp add zuke -- deno run -A zuke.ts mcp ; ajouter --allow-run pour permettre à l'agent d'exécuter les cibles, pas seulement de les inspecter).

Si Deno est déjà installé, vous pouvez aussi utiliser deno task zuke <cible> ou deno run -A zuke.ts <cible>. Le drapeau -A accorde les permissions, car les cibles exécutent généralement des processus et manipulent des fichiers. Ce n'est pas tout à fait équivalent au lanceur : la tâche zuke générée omet délibérément --frozen, donc elle peut guérir un fichier de verrouillage obsolète là où ./zuke échouerait.

Configuration manuelle (sans CLI)

Créez zuke.ts à la racine du projet, étendez Build, déclarez les cibles avec target(), et appelez await run(MyBuild) en bas :

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);

Exécutez avec deno run -A zuke.ts test. (Pour l'expérience de lanceur ./zuke, préférez zuke setup, qui installe les scripts de lancement pour vous.)

Trouver l'API exacte — ne jamais deviner

Chaque outil externe a un wrapper *Tasks typé ; ne retombez pas sur Deno.Command ou du shell fait maison. Confirmez d'abord qu'un wrapper existe — le catalogue ## Packages de llms.txt ou le tableau dans l'antisèche de zuke-write-build est le seul moyen de répondre à cela ; un deno doc par package nécessite un nom cible, il ne peut donc pas révéler qu'un wrapper existe. Une fois que vous connaissez le nom du package, obtenez ses signatures exactes :

• Un seul package en ligne de commande : deno doc jsr:@zuke/<package>. Préférez ceci dans un dépôt consommateur — il résout la version que le projet a réellement installée, il ne peut donc pas décrire une API que cette version n'a pas.
• Toute la surface typée de chaque package se trouve dans llms-full.txt (indexé par llms.txt) — à la racine du dépôt dans le dépôt Zuke lui-même, ou depuis un dépôt consommateur https://raw.githubusercontent.com/zuke-build/zuke/master/llms-full.txt (index : https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt). Les deux suivent master, donc ils peuvent documenter des symboles qui sont fusionnés mais pas encore publiés ; utilisez-les pour trouver ce qui existe, puis confirmez la signature avec deno doc.

Une fois le projet généré, utilisez le skill zuke-write-build pour ajouter et modifier les cibles.