zuke-build/zuke

Zuke in einem Projekt einrichten

Zuke definiert Builds als TypeScript-Klasse, die auf Deno ausgeführt wird. Jedes Ziel ist ein Klassenfeld; Ziele referenzieren einander mittels this.<feld> (niemals Strings). Pakete werden von JSR (jsr:@zuke/...) importiert, nicht von npm.

Der schnelle Weg: zuke setup

Das @zuke/cli-Tool erstellt alles. Installieren Sie es einmal, dann führen Sie setup im Zielprojekt aus:

deno install -A -g -n zuke jsr:@zuke/cli   # einmalig, global
zuke setup                                  # im Projektverzeichnis
./zuke                                       # Build ausführen

Keine globale Installation? Derselbe Assistent läuft direkt:

deno run -A jsr:@zuke/cli setup

setup-Flags: --dir <pfad>, --name <Klassenname>, --force (vorhandene Dateien überschreiben), --yes (nicht-interaktiv), --launcher-name <name> (den Launcher unter einem anderen Namen schreiben, wenn ein zuke/-Verzeichnis bereits existiert — ein Verzeichniskonflikt führt jetzt zu einem ausführbaren Fehler anstatt den Launcher stillschweigend zu überspringen).

Um die API eines @zuke/*-Pakets ohne das @types/node-Rauschen eines Node-Repos zu lesen, führen Sie zuke doc <paket> aus (z. B. zuke doc core) — es führt deno doc in einem isolierten Verzeichnis aus.

Ein bestehendes Projekt migrieren: zuke import

Wenn das Projekt bereits package.json-Skripte oder ein Makefile hat, bevorzugen Sie zuke import gegenüber setup — es liest diese und generiert eine zuke.ts mit einem Ziel pro Aufgabe, einen funktionierenden Startpunkt anstatt eines leeren Builds:

zuke import                  # erkennt package.json automatisch, dann ein Makefile
zuke import --from makefile   # oder Quelle festlegen (package.json | makefile)

Jedes Skript/Ziel wird zu einem target(); ein Befehl wird zu CmdTasks.exec(...) abgebildet — einem Platzhalter, nicht dem Ziel: Bevor Sie ihn akzeptieren, durchsuchen Sie den Paketkatalog (die ## Packages-Liste in llms.txt oder die Tabelle in zuke-write-build's Cheatsheet) nach einem @zuke/<tool>-Wrapper, der zu diesem Befehl passt, und ersetzen Sie den Platzhalter damit — CmdTasks.exec für ein Tool, das einen typisierten Wrapper hat, stehen zu lassen ist ein Fehler, keine Abkürzung. Eine &&-Kette wird zu sequenziellen Schritten, eine run/Voraussetzungsdelegation wird zu .dependsOn(...), und alles, was zu shellspezifisch zum Übersetzen ist (Pipes, Redirects, Umgebungszuweisungen), bleibt hinter einem // TODO erhalten, sodass die Datei trotzdem kompiliert. Es erstellt die Launcher und deno.json genau wie setup und akzeptiert dieselben --dir, --name, --force, --yes-Flags. Danach verwenden Sie die zuke-write-build-Fähigkeit, um alle verbleibenden generierten CmdTasks.exec-Aufrufe durch typisierte *Tasks-Wrapper zu ersetzen.

Was zuke setup schreibt

• zuke.ts — eine Starter-Build-Klasse mit einem Beispiel-Ziel und einem default.
• ./zuke + ./zuke.ps1 — Launcher, die das Projekt lokalisieren und zuke.ts mit dem Deno auf dem PATH ausführen. Wenn Deno fehlt, verweisen sie auf die offiziellen Installationsdokumente und beenden die Ausführung, anstatt ein Installationsskript in eine Shell zu leiten, was nicht verifizierten Code herunterladen und ausführen würde. Sie übergeben --frozen, sobald eine deno.lock existiert, sodass der erste Durchlauf die Lockdatei schreibt und jeder weitere Durchlauf sie überprüft.
• deno.json — zusammengeführt, um eine zuke-Aufgabe hinzuzufügen, sowie fmt/lint/test, falls nicht vorhanden. Die Zusammenführung ist Alles-oder-Nichts: Wenn eine zuke-Aufgabe bereits deklariert ist, wird die Datei vollständig unverändert gelassen, und eine nicht parsebare wird mit einem Hinweis übersprungen.
• zuke.json — { "name": "..." }, markiert das Repo-Root.
• .gitignore — erstellt oder erweitert, sodass .zuke/ ignoriert wird (der Cache und dauerhafte Laufzustand befinden sich dort); unberührt, wenn es bereits abgedeckt ist.

Build ausführen

./zuke                 # Standardziel ausführen  (Windows: .\zuke.ps1)
./zuke <ziel>          # Ein bestimmtes Ziel ausführen
./zuke --list          # Alle Ziele auflisten
./zuke --list --json   # Die gesamte Build-Oberfläche (Befehle, Flags, Ziele) als JSON
./zuke <ziel> --dry-run   # Den Plan anzeigen, ohne auszuführen

Das CLI ist selbstbeschreibend: ./zuke --help gibt die Nutzungsgrammatik plus die Live-Ziele und -Parameter des Builds aus, sodass ein Agent die tatsächliche Befehlsoberfläche entdeckt, anstatt zu raten. Damit ein KI-Client den Build durch typisierte Aufrufe steuern kann, führt zuke mcp einen Model-Context-Protocol-Server darüber aus (registrieren mit claude mcp add zuke -- deno run -A zuke.ts mcp; --allow-run hinzufügen, damit der Agent Ziele ausführen kann, nicht nur inspizieren).

Wenn Deno bereits installiert ist, können Sie auch deno task zuke <ziel> oder deno run -A zuke.ts <ziel> verwenden. Das -A-Flag gewährt Berechtigungen, da Ziele typischerweise Prozesse ausführen und Dateien berühren. Diese sind nicht ganz äquivalent zum Launcher: Die erstellte zuke-Aufgabe lässt --frozen absichtlich weg, sodass sie eine veraltete Lockdatei heilen kann, wo ./zuke daran scheitern würde.

Manuelle Einrichtung (ohne CLI)

Erstellen Sie zuke.ts im Projektverzeichnis, erweitern Sie Build, deklarieren Sie Ziele mit target() und rufen Sie await run(MeinBuild) am Ende auf:

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

Ausführen mit deno run -A zuke.ts test. (Für das ./zuke-Launcher-Erlebnis bevorzugen Sie zuke setup, das die Launcher-Skripte für Sie bereitstellt.)

Die genaue API finden — niemals raten

Jedes externe Tool hat einen typisierten *Tasks-Wrapper; greifen Sie nicht auf Deno.Command oder handgeschriebene Shell zurück. Bestätigen Sie zuerst, dass ein Wrapper überhaupt existiert — llms.txt's ## Packages-Katalog oder die Tabelle in zuke-write-build's Cheatsheet ist der einzige Weg, dies zu beantworten; ein pro-Paket deno doc benötigt einen Namen zum Zielen, kann also nicht offenbaren, dass einer existiert. Sobald Sie den Paketnamen kennen, erhalten Sie seine genauen Signaturen:

• Ein einzelnes Paket auf der Kommandozeile: deno doc jsr:@zuke/<paket>. Bevorzugen Sie dies in einem Consumer-Repo — es löst die Version auf, die das Projekt tatsächlich installiert hat, kann also keine API beschreiben, die dieser Version fehlt.
• Die gesamte typisierte Oberfläche aller Pakete befindet sich in llms-full.txt (indiziert von llms.txt) — im Repo-Root des Zuke-Repos selbst, oder von einem Consumer-Repo aus https://raw.githubusercontent.com/zuke-build/zuke/master/llms-full.txt (Index: https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt). Beide folgen master, können also Symbole dokumentieren, die zusammengeführt, aber noch nicht veröffentlicht sind; verwenden Sie sie, um zu finden, was existiert, dann bestätigen Sie die Signatur mit deno doc.

Sobald das Projekt eingerichtet ist, verwenden Sie die zuke-write-build-Fähigkeit, um Ziele hinzuzufügen und zu bearbeiten.