zuke-write-build

Write or edit a Zuke build

A build is a class that extends Build. Each target is a class field created with target() and made runnable with await run(MyBuild) at the bottom of zuke.ts (no import.meta.main guard — run no-ops on import).

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

class CI extends Build {
  lint = target()
    .description("Lint sources")
    .executes(async () => {
      await DenoTasks.lint();
    });

  test = target()
    .description("Type-check and test")
    .dependsOn(this.lint)
    .executes(async () => {
      await DenoTasks.test((s) => s.allowAll().coverage("cov_profile"));
    });

  // A field named `default` runs when no target is named on the CLI.
  default = target().dependsOn(this.test).executes(() => {});
}

await run(CI);

Non-negotiable rules

1. Dependencies are this.<field> references, never strings. .dependsOn(this.lint), not .dependsOn("lint") — so renames and typos are compile-time errors.
2. A target may only depend on siblings declared above it. Class fields initialise top-to-bottom; a forward reference is undefined and is reported as an error (TypeScript also flags it, TS2729). Order fields so dependencies come first.
3. Check the package catalogue before writing any command. llms.txt's ## Packages catalogue (raw: https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt) and the package table in references/cheatsheet.md are the only ways to answer "does a @zuke/<tool> wrapper exist for this CLI?" — per-package deno doc jsr:@zuke/<pkg> only describes a package whose name you already know; it cannot tell you a wrapper exists. Whatever runs in an .executes(...) body drives an external tool through its namespaced *Tasks object, configured with a settings lambda that mirrors the real CLI's flags — DenoTasks, NpmTasks, DockerTasks, GitTasks, and 30+ more — never a raw Deno.Command or shell string. jsr:@zuke/cmd (CmdTasks.exec) or the $ shell from jsr:@zuke/core/shell is the last resort, reached for only once the catalogue confirms no typed wrapper exists — using it for a tool that has a @zuke/<tool> package is a bug, not a style choice: it discards typed flags, argv purity, and tool resolution. (If a build delegates its side effects to your own tested modules behind injected clients, the wrapper rule still governs whatever those modules run in the target body.)
4. A body is required, unless the target is one of the four forms that replace it: a service(), a .forEach() fan-out, a .waitsFor() gate, or a target declaring only .effect(...). Otherwise set .executes(...); it may be sync or async, and its return value is ignored — .executes(() => DenoTasks.lint()) is fine as-is; never wrap a single wrapper call in an async block just to discard its result.