@zuke/core

Run an external command, ergonomically.

Build an AbsolutePath from one or more segments. The first segment (after joining) must be absolute — start with / or a drive letter, or build from an absolute base — otherwise an error is thrown.

const root = absolutePath("/app");
root("src", "main.ts").path;       // "/app/src/main.ts"
root.join("..", "shared").path;    // "/shared"
absolutePath("C:\\repo", "x").path; // "C:/repo/x"

An immutable, absolute filesystem path with a fluent API.

Build one with absolutePath. The value itself is callable — path(...segments) returns a new path with those segments appended — and the equivalent AbsolutePath.join method does the same. toString() yields the path string, so an AbsolutePath can be interpolated into the $ shell helper and passed straight to tool args().

Configure ExecuteOptions.affected: the base revision and diff seam.

Compute the set of targets in order affected by the given changed files.

order must be a valid execution order (dependencies before dependents, as produced by plan/planGraph) so each target's dependencies are already decided when it is visited. A target is affected when its own inputs cover a changed file, when it declares no inputs (unprovable — treated as affected), when a dependency is affected, or when an affected target triggers it.

Raised when a run has already been resumed by another process.

Raised when an announcement is run before it is fully configured.

A structured announcement assembled by an AnnouncementSettings.

A labelled detail rendered beside the message (e.g. a version or environment).

The outcome an announcement conveys. It drives the accent colour and the icon prepended to the message; defaults to "info".

A clickable action rendered with the announcement (e.g. a link to a release).

Fluent settings shared by every announcement: the message content (a body, an optional title, a level, repeatable detail fields and an action link), an optional display name, the webhook destination, and a fetch seam for tests. All chainers return this. Subclasses add any platform-specific configuration and render the payload.

Announcement task functions for posting build status to chat platforms.

The shape of AnnounceTasks.

The non-generic view of a parameter, used by discovery and resolution.

The CPU architectures Zuke recognises.

Archive a target's outputs into a gzipped tar of their current contents.

Assert that condition is truthy, narrowing it for the rest of the scope. Throws an AssertionError with message otherwise.

Assert that path exists and is a directory. Async (stats the filesystem).

Assert that value is neither null nor undefined, returning it narrowed to its non-nullable type so it can be used inline.

const token = assertExists(Deno.env.get("TOKEN"), "TOKEN is required");

Assert that path exists and is a file. Async (stats the filesystem).

Raised by the assertion helpers when an expectation fails.

Reject an archive entry whose name would escape the destination directory — an absolute path or one with a .. segment (a "zip slip"). A downloaded or poisoned archive must never place files outside where it is being unpacked.

Reject a symlink whose target would resolve outside the destination directory — an absolute target, or a relative one that climbs (with ..) above the extraction root once resolved against the link's own directory. A file entry's name is bounded by assertSafeEntryName; a symlink adds a second escape vector (its target), so a poisoned tarball can't plant bin/x -> ../../etc.

Assert that a tool wrapper conforms: makeSettings() spawns tool, resolves it per options.resolution, and reports a missing binary as a "./tooling.ts".ToolNotFoundError.

makeSettings is called once per check, so each check gets a pristine instance. The resolution check runs against a throwaway temp directory holding a fake node_modules/.bin/<tool> shim, with ZUKE_TOOL_RESOLUTION unset for the duration and restored afterwards; no real subprocess is ever launched.

A wrapper whose run() resolves something at run time must have that pinned inside makeSettings — () => new DockerComposeUpSettings().usePlugin(), say — or the missing-binary check would probe the ambient host. It reports a ToolNotFoundError raised for any binary other than the planted one as a failure, so such a wrapper cannot pass by accident on a host that lacks the real tool.

A bordered panel around content (a string, split on newlines, or an array of lines). Content may carry ANSI codes; padding is measured on the visible text so the border stays flush.

Options for box.

Base class for user-defined builds. Provides no targets of its own; subclasses declare targets as properties. Optionally override the lifecycle hooks.

The incremental cache used by the executor to skip up-to-date targets.

A versioned snapshot of one registered build. Persisted as JSON; a registry's opaque version (an ETag / content hash) drives compare-and-swap writes so two registrations racing at the same version cannot both win.

Where a registered build lives, so a runner can launch it. Two forms: a module (the entry file deno run executes — the form zuke register writes) or an explicit command (a launch argv, for a build fronted by a wrapper script). Both carry the working directory and, in CI, the repository.

Filters for "./registry.ts".BuildRegistry.listBuilds; all fields optional.

Pluggable persistence for BuildDescriptors. version is an opaque token (an ETag or content hash) used for optimistic concurrency: a write only lands if the stored version still matches the one the writer last read, so two registrations racing at the same version cannot both win.

A () => factory the kit calls once to obtain the registry under test.

Result passed to the Build.onFinish lifecycle hook.

A compact registry listing row, returned by "./registry.ts".BuildRegistry.listBuilds.

Options for cancelRun.

The outcome of cancelRun.

Cancel the run options.runId for build: transition it to cancelling (exactly one canceller drives the walk; a live owning process observes the change and aborts), run the compensations of every succeeded target in reverse order, and settle the record as cancelled. Idempotent — cancelling an already-terminal run is a friendly no-op.

Lists the files changed since base (a git revision), each path relative to the repository root. The seam behind ExecuteOptions.affected; defaults to gitChangedFiles and is overridable so the affected plan can be tested without a real git repository.

Run the build-registry conformance scenarios against the registry make builds.

Run the state-store conformance scenarios against the store make builds.

Declare a CI file as a build field. Running the build regenerates it (and the generate-ci command writes it on demand), so the committed configuration is generated from code rather than hand-maintained.

The provider is the only required field: cicd({ provider: "github" }) declares a workflow at .github/workflows/ci.yml that runs the build on push/PR to main. Override only what else you need.

class MyBuild extends Build {
  ci = cicd({ provider: "github" }); // sensible default workflow
  // …or customise:
  gitlab = cicd({ provider: "gitlab", pipeline: { jobs: [{ steps: [...] }] } });
}

A concurrency group: at most one run per group, optionally cancelling the prior one.

A declared CI file. Assign one (via cicd) to a build field and Zuke keeps the file on disk in sync with the definition when the build runs.

A CI configuration file declared on a build: a pipeline bound to a path.

A short identifier for the detected CI host, or "local" when not on CI. Recognises GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines, and the generic CI convention.

Prefer detectCiHost for new code: its values match CiProvider. This function is kept for compatibility and uses longer, host-specific names.

The CI host a build is running on, or "local" when not on CI. The names match CiProvider so they compose with CI generation and per-host integrations (e.g. posting a review to the right pull-request API).

A job: a named unit of work with steps, optionally fanned out by a matrix.

A complete, provider-agnostic CI pipeline.

The CI providers generateCi can target.

A single step in a job.

When the pipeline runs.

A reserved command (graph, generate-ci, completions).

A build's full CLI surface, suitable for JSON serialization.

A built-in option flag.

A parameter declared on the build.

A target declared on the build.

A lazily-executed command. Built by the $ tagged template. The process does not start until the command is awaited or a terminal method (text, lines, code) is called; the result is memoised so repeated reads are cheap.

Raised when a command exits non-zero and throwing was not suppressed.

The resolved result of a command, available when awaiting a Command.

Raised when a command is killed for exceeding its Command.killAfter budget. Thrown regardless of Command.noThrow, since a timeout is a distinct, exceptional outcome from a normal non-zero exit.

A compensation that threw during the cancel walk (recorded, non-fatal).

A predicate gating whether a target runs; may be synchronous or async.

The Zuke config file name; its presence marks a repository root.

A lambda that configures a settings instance and returns it.

Injectable dependencies for runConformanceCli (tests override them).

Tuning options for the conformance scenarios.

The outcome of one conformance scenario.

Options for FileTasksApi.copy.

Options for FileTasksApi.createDirectory.

Read files (relative to cwd), pack them into a tar archive named by their path relative to cwd, gzip it, and write the result to dest.

How often ServiceBuilder.readyWhen is polled while waiting.

The default time a service is given to become ready before it fails.

The default directory a Toolchain (and ToolTasks) installs into.

The built-in renderer: Zuke's ruled headers and summary table.

The real, Deno-backed StateHost.

Define a fluent task for a CLI that has no dedicated @zuke wrapper. Returns a task that runs the tool, configured through a DynamicToolSettings lambda — the same settings-lambda style as the built-in wrappers, with arg/flag/option for argv and the shared cwd/env/noThrow/… chainers.

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

const terraform = defineTool("terraform");
await terraform((s) => s.arg("plan").option("out", "plan.tfplan"));
// → terraform plan --out plan.tfplan

const helmUpgrade = defineTool("helm", { subcommand: "upgrade" });
await helmUpgrade((s) => s.arg("api", "./chart").flag("install"));
// → helm upgrade api ./chart --install

Options for defineTool.

Describe a build's full CLI surface — reserved commands, option flags, targets (with descriptions and dependencies), and declared parameters — as a plain object ready for JSON. This is the same data zuke --list --json prints, made available to tooling and agents that introspect a build in code.

import { describeCli } from "jsr:@zuke/core";
const surface = describeCli(new MyBuild());
console.log(surface.targets.map((t) => t.name));

Pass { omitSecrets: true } to drop .secret() parameters from the result — the posture the build registry uses, so a secret never becomes a spawnable MCP input or crosses the run boundary (zuke register writes this form).

Options for describeCli.

Detect the CI host from the environment. Recognises GitHub Actions (GITHUB_ACTIONS), GitLab CI (GITLAB_CI), Azure Pipelines (TF_BUILD), and Bitbucket Pipelines (BITBUCKET_BUILD_NUMBER); anything else is "local". The reader is injectable so detection can be unit-tested hermetically.

Read the terminal width if available, clamped to a sane range.

Fluent settings for AnnounceTasksApi.discord. Bot mode (.bot().token(t).channel(c)) posts through the REST API with a bot token.

Discover all parallel Group batches declared on a build instance, binding each its property path (for labelling, e.g. in the graph). Groups that are not assigned to a build property simply stay unnamed.

Discover all parameters declared on a build instance: scan its fields (recursing into plain-object component bundles) for Parameter values, bind each its dotted property path, and return a name → parameter map preserving declaration order.

Discover all targets declared on a build instance.

Scans the instance's fields (recursing into plain-object component bundles) for TargetBuilder values, assigns each its dotted property path, and returns a name → target map preserving declaration order.

A download function: fetch url into the file at dest.

Fluent settings for a defineTool tool: build the argv with DynamicToolSettings.arg/DynamicToolSettings.flag/DynamicToolSettings.option (in call order), plus all the shared chainers (cwd, env, noThrow, quiet, toolPath, args).

Resolve a BuildRegistry from the environment, or undefined when none is configured. ZUKE_REGISTRY_URL (with an optional ZUKE_REGISTRY_TOKEN) selects an HttpBuildRegistry; otherwise ZUKE_REGISTRY_DIR selects a FileSystemBuildRegistry.

Resolve a RemoteCacheStore from the environment, or undefined when none is configured. ZUKE_REMOTE_CACHE_URL (with an optional ZUKE_REMOTE_CACHE_TOKEN) selects an HttpCacheStore; otherwise ZUKE_REMOTE_CACHE_DIR selects a FileSystemCacheStore.

Resolve a StateStore from the environment, or undefined when none is configured. ZUKE_STATE_URL (with an optional ZUKE_STATE_TOKEN) selects an HttpStateStore; otherwise ZUKE_STATE_DIR selects a FileSystemStateStore.

The environment variable for a parameter: its path in SCREAMING_SNAKE_CASE.

A SecretSource that runs a command and takes its standard output as the secret value. Configure it through an ExecSecretSettings lambda.

parameter("Vault token").secret().from(
  execSecret((s) => s.command("vault").arg("kv", "get", "-field=token", "secret/ci")),
);

Fluent settings for execSecret: a command whose standard output is the secret. Configure the binary with ExecSecretSettings.command, arguments with ExecSecretSettings.arg, and optionally the environment and working directory. Output is trimmed of surrounding whitespace unless ExecSecretSettings.trim is turned off (some values are whitespace-sensitive).

Execute the requested target and its transitive dependencies.

Runs the build's onStart/onFinish lifecycle hooks around the plan. By default targets run sequentially in deterministic order; with parallel, independent targets run concurrently while dependencies still complete first. Stops launching after the first failure, marks unreached targets as skipped, and returns a failing result.

Options for execute.

Compute the execution set for a requested target: the target plus the transitive closure of its hard dependencies.

A trigger satisfied when a signal named name has been delivered to the run (via zuke resume <id> --signal <name>). The signal's payload is exposed to target bodies through "./target.ts".TargetContext signals.

Options common to extractTarGzip and extractZip.

Read the .tar.gz at src, gunzip and unpack it, and write each entry under destDir (creating parent directories as needed). Symlink entries are recreated as symlinks and directory entries as directories; pass ExtractOptions.strip to drop leading path components.

Read the .zip at src, unpack it, and write each entry under destDir (creating parent directories as needed) — the zip counterpart of extractTarGzip. Entry names are validated so a malicious archive cannot escape destDir.

Throw an AssertionError with message. Never returns.

Options for fanOutPipeline: how a build's targets become parallel CI jobs.

Expand a build's target graph into a fanned-out pipeline: one CI job per runnable target, wired together with needs: edges that mirror the targets' dependsOn dependencies — so independent targets run in parallel and a target's job waits for its prerequisites. Each job runs just its own target; upstream outputs are shared through the remote cache, so configure one (e.g. ZUKE_REMOTE_CACHE_* on the jobs) to avoid rebuilding dependencies in every job.

base contributes the pipeline-level fields (name, triggers, permissions, concurrency); its jobs are ignored in favour of the generated ones. Targets with no body, and (unless FanOutOptions.includeUnlisted) unlisted targets, are omitted, and needs edges to omitted targets are dropped.

A SecretSource that reads a file and takes its content as the secret value — for a mounted Kubernetes/Docker secret or a CI-provided file. Configure it through a FileSecretSettings lambda.

parameter("Registry password").secret().from(
  fileSecret((s) => s.path("/run/secrets/registry_password")),
);

Fluent settings for fileSecret: read a secret from a file. Set the path with FileSecretSettings.path; the content is trimmed of surrounding whitespace unless FileSecretSettings.trim is turned off.

A BuildRegistry that writes one <id>.json file per build under a directory.

Security. dir is *trusted configuration* — the location you choose to store the build catalog (from ZUKE_REGISTRY_DIR or an explicit registry), the same posture as "../state/fs_store.ts".FileSystemStateStore. The only untrusted value that reaches a path is the build id, validated at every point a path is built, so a traversal cannot be smuggled in via an id.

A RemoteCacheStore backed by a shared or mounted directory.

A StateStore that writes one <id>.json file per run under a directory.

Security. dir is *trusted configuration* — the location you choose to store run state (from ZUKE_STATE_DIR, --state, or an explicit store), the same posture as "../remote_cache.ts".FileSystemCacheStore. The only untrusted value that reaches a path is the run id, which is validated at every point a path is built, so a traversal cannot be smuggled in through an id.

Filesystem task functions for build scripts.

The shape of FileTasks.

Detect a cycle in the hard-dependency (dependsOn) graph across all targets.

Builds one item's ordered pipeline of sub-targets for TargetBuilder.forEach. The returned record's keys are stage names and its values are targets; each stage implicitly depends on the one declared before it, so an item's stages run in insertion order.

One materialised fan-out item: a unique label plus its pipeline stages.

Fluent configuration for TargetBuilder.forEach, in the settings-lambda style: .forEach(items, factory, (s) => s.concurrency(3).continueOnItemFailure()). Sets the concurrency cap and whether one item's failure isolates it or stops the whole batch.

The internal fan-out spec stored by TargetBuilder.forEach. Its ForEachSpec.materialize closure captures the item type, so the runtime list and factory are erased to concrete ForEachItems the executor can run without knowing the item type.

Format a duration in milliseconds as 1.2s.

Render pipeline as the YAML configuration for provider: .github/workflows/*.yml, .gitlab-ci.yml, azure-pipelines.yml, or bitbucket-pipelines.yml. The pipeline may be empty ({}) to accept every default.

List the files changed since base (default HEAD) via git: tracked changes versus base plus untracked files not covered by .gitignore. run invokes git and returns stdout (defaults to a real git subprocess); override it to test without a repository.

Expand a glob pattern to the matching paths, relative to cwd, sorted for determinism. The walk starts at the pattern's static prefix, so anchor patterns (e.g. src/**\/*.ts) to avoid scanning the whole tree. Symlinked directories are not followed.

Options for glob.

Compile a glob pattern into an anchored RegExp that matches a full path. Exposed (and pure) for testing and custom matching.

Raised when the build graph is invalid (cycle or unknown dependency).

Create a parallel Group. Targets join it with TargetBuilder.partOf, and a downstream target can depend on the whole batch by passing the group to TargetBuilder.dependsOn.

checks = group();
lint = target().partOf(this.checks).executes(...);
format = target().partOf(this.checks).executes(...);
deploy = target().dependsOn(this.checks).executes(...);

A parallel batch of targets, created with group. Targets join it via TargetBuilder.partOf; its members run concurrently with one another (each still awaiting its own dependencies) regardless of the global parallel setting. Passing a group to TargetBuilder.dependsOn depends on every member at once.

Gunzip-decompress data using the platform DecompressionStream.

Gzip-compress data using the platform CompressionStream.

The current host's Platform (from Deno.build, with the OS normalised) — the analogue of "./host.ts".isCI for "what machine am I running on". Its os is a Zuke OperatingSystem (macos, not darwin); use the osLabel/archLabel helpers to name it for a download URL.

const p = hostPlatform();
p.os;                                          // "linux" | "macos" | "windows"
const cpu = p.archLabel({ x86_64: "amd64", aarch64: "arm64" });

A BuildRegistry backed by HTTP.

Security. The url and token are *trusted configuration* — build descriptors (structural CLI metadata plus a launch location) are sent to that host, so point it only at a service you control and prefer a secret parameter or environment variable over a hard-coded value.

Configuration for an HttpBuildRegistry.

A RemoteCacheStore backed by HTTP: GET <url>/<key> fetches an artifact (a 404 means a miss) and PUT <url>/<key> stores one. Works with any object store or cache server that speaks plain HTTP GET/PUT — an S3, GCS, or R2 bucket behind a URL, or a self-hosted cache endpoint.

Security. The url (and token) are *trusted configuration*: outputs are uploaded to that host and archives are extracted from it, so point it only at a cache you control, and prefer a secret parameter or an environment variable over a hard-coded value. On CI, restrict egress to the cache host so a misconfigured or overridden URL can't exfiltrate artifacts. Restored archives are always confined to the workspace (see restoreOutputs), so a poisoned store cannot write outside it.

Configuration for an HttpCacheStore.

Download url to dest, streaming the response body to the file. Creates or truncates dest. Throws HttpError on a non-2xx status.

Raised when an HTTP request returns a non-2xx status. The URL appears in the message and on url, so it is passed through redactUrl first — userinfo and credential query params never reach a log.

Fetch url and parse its body as JSON. Throws HttpError on non-2xx.

Options shared by the HTTP helpers.

A StateStore backed by HTTP.

Security. The url and token are *trusted configuration* — run records (which include resolved non-secret parameters and target metadata) are sent to that host, so point it only at a service you control and prefer a secret parameter or environment variable over a hard-coded value.

Configuration for an HttpStateStore.

Fetch url and return its body as text. Throws HttpError on non-2xx.

Provision an npm-registry package as a version-pinned, cached tool and return the installed bin's AbsolutePath — hand it straight to a wrapper's .toolPath(...).

The package installs under <destDir>/npm/<name>@<version> via npm install --prefix <dir> --no-save <name>@<version>; a marker file records the pinned { name, version }, so a later run whose marker matches and whose bin is still present is reused without invoking npm again. npm must be on PATH (it resolves and downloads the package).

Throws — without recording a marker — if spec is malformed (an unsafe name, version, or bin), if npm fails, or if npm succeeds but the expected bin is absent (a typo'd bin, or a package that ships no executable), so a bad install fails loudly here instead of at a later .toolPath(...).

The marker is written only after the bin is verified present, so a matching marker always has its bin — a reader never sees a half-written install. Concurrent installs of the same pin into the same directory are not isolated; they just do redundant work (the documented ceiling — a build resolves its toolchain once, and distinct pins use distinct directories).

Options for installNpmTool.

The host identity: a Zuke OperatingSystem and Architecture.

Download and install a release binary, returning its AbsolutePath. The path is ready to hand to a wrapper's .toolPath(...) (or CmdTasks).

With a InstallReleaseOptions.checksum, the download is verified before anything is installed, and a matching prior install is reused without downloading again — so pinning a checksum makes the install both hermetic (tamper-evident) and cached.

Options for installRelease.

Download and unpack a whole archive tree — a multi-file runtime such as Node.js, which ships bin/node, bin/npm, bin/npx, and lib/node_modules/** in one tarball — and return the AbsolutePath of its (stripped) root. installRelease extracts a single binary; installTree keeps the entire directory, symlinks included.

Because AbsolutePath is callable, the root doubles as an accessor: root("bin", "node") is the node binary and root("bin") is the directory to put on PATH (with prependPath). Declared InstallTreeOptions.bins are marked executable on POSIX. With a InstallTreeOptions.checksum the archive is verified before unpacking and a matching prior install is reused.

Options for installTree.

A value that may be interpolated into a $ template.

Whether the build appears to be running in a CI environment.

Whether a string names one of the SGR styles.

A JSON-serialisable value — the only thing that may be persisted in a target's TargetStateHandle, since run state is stored as JSON.

A horizontal rule spanning the style's width (dimmed by default).

Options for line.

Raised when a target's lock is already held by another run. Its message is the rendered guidance (from the target's onConflict, else a default), so it surfaces verbatim in the CLI failure footer and the run record; holder carries the structured identity for programmatic surfaces (e.g. MCP).

Who holds a lock — surfaced to the loser of a conflict so it can act.

Join parts into a lock key that is safe to use as a filename and URL segment. Each part is sanitised (non-[A-Za-z0-9._-] runs become _) and empty parts are dropped, so lockKey("deploy", repo) is stable and injection-free.

The result of StateStore.acquireLock: a token proving ownership, or the current holder when the lock is already held.

Fluent configuration for TargetBuilder.lock, in the settings-lambda style: .lock((s) => s.lockKey("deploy", repo).withTtl("4h")). Set the key (composed from sanitised parts with LockSettings.lockKey, or directly with LockSettings.key), the TTL, and an optional LockSettings.onConflict message. The lambda runs after parameters resolve, so the key may read this.<param>.value.

A trusted caller identity, resolved per request by a McpIdentityHook (typically from an authenticating reverse proxy's header). Its McpIdentity.actor is the highest-precedence attribution — it overrides --actor, the environment, and the client's self-reported label for the call.

Resolve a trusted McpIdentity from a request's context. Invoked once per message, before any dispatch; throwing rejects the whole request with an auth error, so nothing executes and nothing is written to state — the seam a proxy in front of the server uses to inject an authenticated identity.

The per-request context a transport hands the message handler. Carries the request's headers, so a server's identity hook can authenticate the caller from a trusted proxy header. Empty on the stdio transport (no headers).

Point settings at a binary that cannot exist, so running it raises a "./tooling.ts".ToolNotFoundError without ever launching a real process — the way a wrapper test proves each of its task functions reaches execution.

The platform is pinned to linux because on Windows a missing binary is retried through cmd /c, which exists, so the failure would surface as a command error instead:

await assertRejects(() => BiomeTasks.check(missingTool), ToolNotFoundError);

Runs npm install <args> — the injectable subprocess seam. Defaults to spawning the ambient npm; a test injects a fake that records the argv and plants the expected bin, so provisioning stays hermetic and network-free.

A specification of an npm-registry package to provision as a tool.

A compensation registered with TargetBuilder.onCancel: either a sibling target directly, or a thunk returning one. The thunk form defers evaluation so a compensation declared *below* the target it cleans up (class fields initialise top-to-bottom) can still be referenced.

What a timed-out wait does — resolved from WaitSettings.onTimeout.

Optional extras for openCache: a remote store and a warning sink.

The operating system as a Zuke OperatingSystem: darwin becomes macos, windows stays windows, and every other Unix (linux, the BSDs, solaris, …) is reported as linux. Pass a raw Deno.build.os value to normalise it; defaults to the running host — the platform analogue of isCI.

import { operatingSystem } from "jsr:@zuke/core";
if (operatingSystem() === "macos") { ... }

The operating systems Zuke recognises — Deno's raw Deno.build.os values normalised to a friendly set (notably darwin → macos). Used across the ecosystem so builds branch on "macos" rather than the surprising "darwin".

A soft ordering edge [before, after]: before must run before after, with no data dependency. Returned by "./build.ts".Build.extraEdges to feed a consumer's dependency graph (e.g. a monorepo's dependency-graph.json) into planning; an edge whose endpoints are not both in the run's execution set is ignored, and cycles are reported like any other.

Filesystem effects used to archive and restore a target's outputs.

Pad text to width visible columns, aligning left (default) or right.

Wrap text in ANSI codes when colour is enabled, otherwise return it as-is.

Create a new build parameter (a string by default). Configure it fluently: .number()/.boolean() change the kind, .options(...) restricts a string, .default(v)/.required() set optionality, and .env(name) overrides the environment variable.

A typed build parameter. Declare one with parameter and configure it with the fluent methods; each method returns a new parameter whose value type reflects the configuration (string, number, boolean, and whether it can be undefined).

K is the underlying value kind; T is the exposed value type, which is K for required/defaulted parameters and K | undefined for optional ones.

Raised when a parameter value is invalid or read before resolution.

A parameter's runtime kind tag.

The value kinds a parameter can hold.

Parse a duration to milliseconds. Accepts a number (already milliseconds) or a string of a non-negative amount and a unit — ms, s, m, h, or d (e.g. "90s", "4h", "1.5h"). Throws a friendly error on anything else.

A filesystem path accepted by Zuke APIs: either a plain string or an AbsolutePath. Anywhere a tool wrapper or build helper takes a path, it accepts a PathLike and coerces it to a string.

Topologically sort the execution set for root, honouring hard dependencies and the soft before/after ordering hints (the latter only between nodes that are both in the set).

A platform with helpers to name it the way a tool's downloads do. osLabel and archLabel map the os/arch to a tool's own naming, falling back to the value itself for anything not in the alias map — so a url callback reads p.osLabel({ macos: "darwin" }) (for a tool that spells macOS "darwin") instead of a hand-written os === … ternary. This is what the InstallReleaseOptions.url and InstallReleaseOptions.checksum callbacks receive.

A lifecycle observer. Every hook is optional; implement only the ones you need. Hooks may be async — the executor awaits each before continuing.

Prepend dir to the process PATH, and return the new value. A tool provisioned into dir (e.g. the bin directory of an "./install.ts".installTree runtime) then resolves for the rest of the build: the shell $, Command, and every tool wrapper spawn subprocesses that inherit Deno.env, so the node_modules/.bin shims and NpmTasks that assume a node/npm on PATH find the provisioned one.

Idempotent — a directory already on PATH is left in place, not duplicated — and uses the platform separator (; on Windows, : elsewhere).

The result of a BuildRegistry.register compare-and-swap write.

The result of a StateStore.putRun compare-and-swap write.

The placeholder a Redactor substitutes for each secret value.

Collects secret values and masks them in text. Register a value with Redactor.add and rewrite a line with Redactor.redact; empty strings are ignored (they would match everywhere) and duplicates are recorded once. Longer secrets are applied first so a secret that contains another is masked whole rather than partially.

A recovery step plugged into a target with TargetBuilder.recoverWith. It runs only after the target body fails, receives the failure, and may attempt to repair it — returning { retry: true } to ask the executor to re-run the body (the real build command is the verifier). Implemented, for example, by the AI fixer in @zuke/ai, but any object with a remediate method qualifies.

Context passed to a Remediation after a target body fails.

The outcome of one Remediation attempt.

The store key for a target's outputs: its name and input fingerprint. The name is sanitised so the key is safe as a filename and a URL path segment.

A content-addressed store for archived target outputs, keyed by remoteCacheKey. Both operations are best-effort from the build's point of view: the executor never fails a build because the store is unreachable — it just rebuilds and, where it can, re-uploads.

Options for FileTasksApi.remove.

How the executor renders a build's output. Each method is pure — it returns the lines to print rather than writing them — so a custom renderer stays unit-testable and the executor keeps control of the output streams.

The absolute path of the repository root — the directory containing CONFIG_FILE — with any segments appended. The returned value is an AbsolutePath, so it is itself callable for further joining.

repoRoot();                  // <root>
repoRoot("src", "main.ts");  // <root>/src/main.ts
repoRoot().join("dist");     // <root>/dist

The root is located by walking up from the current working directory, so the path is resolved at runtime and never hard-coded into a committed file.

Sink for executor output, defaulting to the console. Overridable in tests.

Pick the build registry by precedence: an explicit option wins (false disables the registry entirely), then a declared registry (a build's registry() override), then the envBuildRegistry environment fallback, then — only when ResolveRegistryOptions.enableDefault — a filesystem registry under <root>/.zuke/builds.

Inputs resolveBuildRegistry needs to build the default filesystem registry.

Pick the remote store for a run by precedence: an explicit option wins (false disables the remote cache entirely), then a declared store (a build's remoteCache() override), then the envCacheStore environment fallback.

Inputs resolveStateStore needs to build the default filesystem store.

Pick the state store for a run by precedence: an explicit option wins (false disables state entirely), then a declared store (a build's stateStore() override), then the envStateStore environment fallback, then — only when ResolveStateOptions.enableDefault — a filesystem store under <root>/.zuke/runs. A plain build with no durable feature and no configuration gets undefined, so it carries zero overhead.

Restore the files in artifact (a gzipped tar produced by archiveOutputs) to disk, returning the paths written. Entry names are validated first: an absolute path or one escaping the workspace (..) is rejected before anything is written, so a malicious archive can't plant files outside the current directory.

Re-attempt every suspended run in the store (or just runId): predicate-based waits are re-evaluated and expired waits time out. Signal-based waits with no new signal simply re-suspend. Returns the number of runs that ended in failure. This is the sweep a cron or webhook drives (zuke resume --check).

A run whose record is "./state/types.ts".RunRecord.degraded is counted as failed on every sweep until an operator resolves it: it cannot be advanced without deciding whether its targets are safe to repeat, and a non-zero result is the only channel a cron watches. Its refusal is reported through the reporter (the console unless silenced) so the cause is visible, and it stays suspended, so a later sweep with ResumeOptions.resumeDegraded still picks it up.

Options for resumeRun.

Resume the suspended run options.runId for build. Transitions it to running (exactly one resumer wins), optionally delivers a signal, checks the graph still matches, and continues via "./executor.ts".execute, re-running only the not-yet-succeeded targets.

The continuation state resumeRun hands to execute on a resume.

A trigger satisfied when an async check predicate returns true. Zuke does not poll on its own — the predicate is evaluated when the target is reached and on each zuke resume <id> --check, so a cron or webhook nudging --check drives it. Use it to wait on state Zuke can query (a row, a file, an API).

Options for resumeWhen.

Public entry point. Instantiate the build, parse arguments, run, and set the process exit code.

Call it at the bottom of your build file — no import.meta.main guard needed. run acts only when its module is the program's entry point; when the file is imported instead (for example under test) it does nothing.