Authoring targets

A target is declared as a class field on a Build subclass, built up through the fluent TargetBuilder that target() returns. Every configuration method is chainable and returns this; the only thing required before a target can run is a body, set with .executes(...). This page is the authoritative index of what a target can declare — each method, its exact signature, and where the deeper features are documented in full.

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("Run the test suite")
    .dependsOn(this.lint)
    .executes(async (ctx) => {
      // ctx is optional: runId, target, signal, state, signals, dryRun
      await DenoTasks.test((s) => s.allowAll());
    });
}

await run(Ci);

Dependencies are passed as sibling references (this.lint), never as strings: the framework maps each builder back to its field name during discovery. Because class fields initialise top-to-bottom, a target can only reference siblings declared above it — a forward reference is undefined at runtime (and TypeScript flags it as TS2729).

Declaration

The basics: what the target is — its summary, its body, whether it is visible, and how it advertises itself. group() creates a parallel batch; a target joins one with .partOf(group) and its members then run concurrently with one another even in an otherwise sequential build (each still waiting for its own dependencies). Passing the group to another target's .dependsOn(...) depends on every member at once.

checks = group(); // declare the batch above the members that join it

clean = target().executes(/* … */);
lint = target().dependsOn(this.clean).partOf(this.checks).executes(/* … */);
format = target().dependsOn(this.clean).partOf(this.checks).executes(/* … */);

deploy = target()
  .dependsOn(this.checks) // one edge; waits for lint and format
  .executes(/* … */);

Dependencies & ordering

.dependsOn(...) declares hard prerequisites: they are pulled into the plan and run first, transitively. Ordering methods (.before()/.after()) are soft: they only reorder targets that are already in the plan and never pull new ones in. Both .dependsOn() and .consumes() accept a group, which expands to every member.

lint = target()
  .description("Lint sources")
  .after(this.restore) // if restore is in the plan, run after it
  .before(this.test) // if test is in the plan, run before it
  .executes(async () => {
    await DenoTasks.lint();
  });

Conditional execution & caching I/O

.onlyWhen(condition) gates whether a target runs; the rest declare the target's cache footprint. A target that declares .inputs(...) becomes incremental — Zuke fingerprints those paths (SHA-256, directories hashed recursively) and reports the target cached when the fingerprint is unchanged since the last successful run and every declared .outputs(...) still exists.

compile = target()
  .inputs("src", "deno.json") // re-run only when these change…
  .outputs("dist") // …or when dist is missing
  .cacheKey(() => this.configuration.value) // …or when config changes
  .executes(async () => {
    await DenoTasks.run((s) => s.script("build.ts"));
  });

A target with no inputs and no cache keys always runs. Fingerprints live in .zuke/cache.json; a cached/skipped target counts as satisfied, so its dependents still run. See Caching for the fingerprint algorithm, the cache key, and the output semantics in full.

Lifecycle & validation

Checks around the body and how failure is handled. A Validation is any object with a validate(ctx) method: .validateBefore() runs its checks before the body (a throw skips the body and fails the target); .validateAfter() runs them after a successful body. Both are repeatable and order-preserving, and a cached/skipped target runs neither. .timeout() and .retry() compose — the timeout is per attempt.

const noSecrets: Validation = {
  name: "no-secrets",
  validate: async () => {/* scan the diff; throw on a hit */},
};

deploy = target()
  .validateBefore(noSecrets) // a throw skips the body and fails the target
  .executes(async () => {/* … */});

flaky = target()
  .timeout(30_000) // each attempt may run up to 30s…
  .retry(2, 1_000) // …retried twice, 1s apart, on failure
  .proceedAfterFailure() // don't abort the rest of the build if it still fails
  .executes(async () => {
    await fetch("https://example.com/health");
  });

Triggers & CD

.triggers(...) is the inverse of .dependsOn(...): running this target pulls the listed targets into the plan and runs them after it — a deploy that triggers a notify, say. Unlike .before()/.after() (which only reorder), it adds targets to the plan.

Resilience & orchestration

The long-running and self-healing surface. Each of these has a dedicated page — the row here is the signature and a one-line summary; follow the cross-link for the full model. The three settings-lambda methods (.lock, .waitsFor, .forEach) take a Configure<Settings> function, run after parameters resolve, so the lambda may read this.<param>.value. .lock, .waitsFor, and .onCancel require a state store.

import { externalSignal, target } from "jsr:@zuke/core";

awaitApproval = target()
  .dependsOn(this.deploy)
  .waitsFor((s) =>
    s.on(externalSignal("testing-approved"))
      .timeout("72h")
      .onTimeout(() => this.rollback)
  )
  .onCancel(() => this.rollback); // undo the deploy if the run is cancelled

For the full framework surface beyond the builder — components, assertions, FileTasks, HTTP and compression helpers, host detection, and the Build lifecycle hooks (onStart/onFinish) — see Concepts and the standard library.