Programmatic API

A zuke.ts is usually driven by the CLI. But @zuke/core exports the same building blocks the CLI uses, so you can drive a build yourself — run a target from another program, assert on the result in a test, or introspect a build's command surface without shelling out and parsing --help. Every name below is a real export of mod.ts; the CLI is just a thin layer over them.

The building blocks

run is the top of the stack — the one call a build file makes. Underneath it, execute runs a resolved plan, and a family of pure functions inspect the dependency graph:

import {
  discoverTargets, // (build) => Map<string, TargetBuilder>
  execute, // (build, rootTarget, options?) => Promise<BuildResult>
  executionSet, // (rootTarget) => Set<TargetBuilder>
  findCycle, // (targets) => string[] | null
  GraphError,
  plan, // (rootTarget) => TargetBuilder[]  (topological order)
  validateGraph, // (targets) => void  (throws GraphError)
} from "jsr:@zuke/core";

run — the entry point

run(BuildClass, options?) is what you call at the bottom of a build file. It instantiates the build, parses Deno.args, runs the requested command, and sets the process exit code. It returns Promise<void> and calls Deno.exit itself, so it's the launcher, not the seam you drive a build through in code — for that, reach for execute.

import { run } from "jsr:@zuke/core";
import { consoleRenderer } from "jsr:@zuke/console";

class MyBuild extends Build { /* … */ }

// The same entry point the ./zuke launcher uses, with a plugin and a renderer.
await run(MyBuild, {
  plugins: [timingPlugin],
  renderer: consoleRenderer,
});

execute — run a plan in code

execute(build, rootTarget, options?) is the workhorse. It resolves the build's parameters, plans the graph from rootTarget, runs each target body in order (or concurrently with parallel), and resolves to a BuildResult — it never calls Deno.exit, which is exactly what makes it testable. The rootTarget is a TargetBuilder, which you get from discoverTargets.

import { discoverTargets, execute } from "jsr:@zuke/core";
import { MyBuild } from "./zuke.ts";

const build = new MyBuild();
const target = discoverTargets(build).get("test");
if (target) {
  const result = await execute(build, target, { parallel: true, cache: false });
  console.log(result.ok ? "green" : "red");
}

The result carries everything the caller needs to react to the run:

interface BuildResult {
  ok: boolean; // every executed target passed (also true for a suspended run)
  executed: string[]; // target names, in execution order
  error?: unknown; // the error that aborted the run, if any
  suspended?: boolean; // parked at a .waitsFor(...) gate; state was saved
  cancelled?: boolean; // stopped via signal / `zuke cancel`; ok is false
  runId?: string; // this run's id, for `zuke runs show` / `zuke cancel`
}

ok is true when every executed target passed — including a run that suspended at a .waitsFor(...) gate (the process would exit 0). A cancelled run — via options.signal / Ctrl-C, or another process running zuke cancel — is ok: false with cancelled: true, after its compensations have run.

execute options

ExecuteOptions mirrors the CLI flags, plus a few seams that exist only for embedding and testing. Every field is optional.

import { discoverGroups, discoverTargets } from "jsr:@zuke/core";

const build = new MyBuild();
const targets = discoverTargets(build); // Map<string, TargetBuilder>

targets.get("test"); // a top-level target
targets.get("release.publish"); // a component target, under its dotted path

// discoverGroups(build) does the same for declared parallel groups.

import { describeCli } from "jsr:@zuke/core";

const cli = describeCli(new MyBuild());
for (const t of cli.targets) console.log(t.name, "→", t.dependsOn.join(", "));

// Drop .secret() parameters from the surface (what `zuke register` writes):
const safe = describeCli(new MyBuild(), { omitSecrets: true });

import { defaultRenderer, execute, type Renderer } from "jsr:@zuke/core";

const quiet: Renderer = {
  ...defaultRenderer,
  // Override only the hooks you want to change…
  targetHeader: () => [],
};
await execute(build, target, { renderer: quiet });

import { execute, type BuildCache } from "jsr:@zuke/core";

// A minimal in-memory cache — never touches .zuke/cache.json.
const cache: BuildCache = {
  upToDate: async () => false,
  record: async () => {},
  save: async () => {},
};
await execute(build, target, { cache });

import {
  discoverTargets,
  GraphError,
  plan,
  validateGraph,
} from "jsr:@zuke/core";

const build = new MyBuild();
const targets = discoverTargets(build);

try {
  validateGraph(targets); // throws GraphError on a missing ref or a cycle
} catch (error) {
  if (error instanceof GraphError) console.error(error.message);
}

// The topological order a run would execute, without running anything:
const order = plan(targets.get("release"));
console.log(`${order.length} targets, in execution order`);