@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().

Take a lease named prefix over runId, or null if a live holder has it.

While held, the lease renews on a background heartbeat until HeldLease.release. That timer never keeps the process alive.

Only an explicit refusal counts as loss. A store reports false from a renewal when the claim is demonstrably somebody else's; it *throws* for a filesystem mutex it could not take in time, or an HTTP 503, or a DNS blip — none of which say anything about who holds the lease. Treating those as loss would abort a healthy build because the state service had a bad second, so they are swallowed and the next tick tries again. A store that stays unreachable lets the claim lapse at its TTL, which is the documented backstop and the honest outcome.

Whether a person or a machine asked for a run (see RunInitiator).

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.

Append markdown to the Actions job summary, returning whether it was written. Outside Actions (no GITHUB_STEP_SUMMARY) it is a no-op returning false, so the same code path works locally.

Best-effort by design: an unwritable summary file reports false rather than throwing. A report that could not be *displayed* must never fail the build that produced it — the build's own result is the signal that matters.

The CPU architectures Zuke recognises.

A packed download format, unpacked after the checksum is verified.

Archive a target's outputs into a gzipped tar of their current contents. A declared output that does not exist is skipped, as is anything under a .git or .zuke directory.

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 WWW-Authenticate: Bearer challenge built from parts.

Returns a bare Bearer when nothing usable is supplied, and drops any single part that survives filtering as empty, so a caller cannot produce a malformed header by passing an odd string.

The parts of a WWW-Authenticate: Bearer challenge Zuke emits.

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.

Settings for BrowserTasks.open. The binary and argv are derived from the platform (ToolSettings.os_); the shared chainers (quiet, noThrow, toolPath, …) apply as on any tool.

Task functions for the user's browser.

The shape of BrowserTasks.

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.

How a bearer challenge names the failure, when there is one to name.

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.

The action a CiCheckout is generated from when pins are resolved.

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

A pinned action reference, and the version its commit corresponds to.

The version is emitted as a trailing # v1.2.3 comment, which is not decoration: Dependabot reads it to know which version a pinned SHA is, and rewrites both together when it bumps. A generated workflow that dropped it would leave automated bumps with no version to track.

The single step every GitHub job starts with: the zuke-build/zuke composite action, which hardens the runner, checks the repository out, and installs Deno if asked — the three steps a Zuke job used to spell out separately.

It is the default because those three are not three decisions. They are one prelude whose parts only work in one order, and writing them out three times per workflow meant three pinned SHAs to keep current in every generated file rather than one, inside an action that is itself versioned and tested.

The CiHardenRunner and CiCheckout options are still how a job configures it — they become the action's inputs. What changes is how many steps that renders, not what a build declares. A job that opts out of either with harden: false or checkout: false falls back to the separate steps, since one action cannot do half of itself.

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: [...] }] } });
}

The repository checkout, emitted as an actions/checkout step after any CiHardenRunner and before the job's own steps. Like hardening, the pinned action reference is required.

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.

Runner hardening, emitted as a step-security/harden-runner step before anything else in the job.

This cannot move into the build: the point of the step is to install an egress control *before* build code runs, so a build that set it up itself would be the very code it is meant to contain. Generating it is the next best thing — the policy is declared in one place, in code, next to the job it protects.

The pinned action reference is required rather than defaulted. A default would mean either a floating tag (which supply-chain scanners reject as an unpinned use) or a commit SHA baked into @zuke/core that goes stale between releases. Passing it makes the pin the caller's — and lets a build source it from wherever its bumps are automated.

A short identifier for the detected CI host, or "local" when not on CI. Recognises GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines, and — as the generic "ci" — the common markers other systems set, including Jenkins, Buildkite, CircleCI, Travis and TeamCity.

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

One job's worth of a workflow, derived from a target.

A job's shape is almost entirely implied by the target it runs: the id and display name come from the target, the command is ./zuke <target>, and the needs: edges come from the target's dependsOn. So an invoked target usually needs nothing said about it at all — pass the target and the job is generated.

The fields here are the residue that genuinely cannot be inferred, because they are properties of the *runner* rather than of the work: which OS matrix to fan out over, which token scopes the job needs, how much egress to permit, how long to allow. Set one only when the default is wrong.

A target to invoke, bare when the derived job needs no adjustment.

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

Resolves an action's pinned reference by name, e.g. "actions/checkout".

Supplying one is what lets a workflow declare hardening and checkout by *intent* rather than by repeating a SHA at every use. Without it each CiHardenRunner and CiCheckout must carry its own action.

A complete, provider-agnostic CI pipeline.

The CI providers generateCi can target.

A single step in a job.

Filesystem seams for syncCiFiles (overridable for tests).

The outcome of syncing one CiFile.

What syncCiFiles did to a file.

When the pipeline runs.

A step's uses: value — a bare reference, or one carrying its version.

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.

The sink every command-surface module writes through, neutralised for a GitHub Actions runner.

These commands echo arguments the invoker chose — a run id, a target name, a force reason — and read values another process wrote into the shared state store. Under Actions those commonly come from a workflow-dispatch input or an issue body rather than from a person at a terminal, and a thrown message quotes them straight back.

A sink rather than a guard at each of the sixty-odd writes, because none of them should be exempt: unlike the run's reporter, none of these modules emits a workflow command of its own, so there is no half to carve out. The MCP command writes only diagnostics here — its protocol never goes through the console — so escaping cannot corrupt it.

The decision is made per line, not once when this module loads. A top-level constant would read the environment at import time, before an embedder or a test has set it, and the escaping would then silently not apply.

Public so a companion command surface — @zuke/cli is one — can write through the same sink instead of composing a copy of it. It is the sink for a command's own diagnostics and output, not the reporter handed to execute: the run's renderer writes ::group:: and ::endgroup:: of its own and wraps only third-party text in escapingReporter beside them, and a sink that neutralises every leading :: would break that grouping.

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.

Receiving the context is optional — a zero-argument .onlyWhen(() => …) stays valid, since a zero-argument function is assignable to this one-parameter type.

The context a condition receives.

Deliberately narrower than a TargetContext. A condition on a .whenSkipped("skip-dependencies") target is evaluated before the run starts, to decide what the run prunes — at which point the run's identity, its durable state handles, and its cancellation signal do not exist yet. This type carries only what is available at every moment a condition can be called.

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.

One effect declared on a target: its name and its body.

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 shipped default policy.

| Call | Needs | | --- | --- | | list_* / show_* / describe_* | read | | run:<target> | run, and the target's requiresRole when it declares one | | a run-scoped mutation | the run's initiator, or operator | | a sweep over every run | operator |

A run whose initiator is a service may be steered by any caller holding run: a scheduler's run has no person to ask, and treating the scheduler as its owner would mean nobody could intervene. Documented, and overridable by Build.mcpAuthorize.

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.

The executable that runs Deno here — what to spawn when a build needs deno itself, rather than a tool it installed.

Under deno run the executable running this code is Deno, so Deno.execPath() names it and nothing has to be looked up: a project whose Deno came from the ./zuke launcher rather than from PATH still works, and the subprocess is the same version as the parent.

A build compiled with deno compile is not Deno. There Deno.execPath() is the compiled binary, so spawning it re-enters the build instead of running Deno — deno test becomes the build running itself with test as a target, and deno doc <spec> becomes the build being asked for a target named doc. The compiled case therefore resolves the bare name and lets the OS find a real Deno on PATH. Deno.build.standalone is what tells the two apart.

import { denoExecutable } from "jsr:@zuke/core";
const deno = new Deno.Command(denoExecutable(), { args: ["doc", "jsr:@zuke/core"] });

@zuke/cli answers the same question with one more step — a compiled global zuke falls back to the launchers' bootstrap directory when PATH has no Deno — because it is the command a user installs on a machine that may have no Deno at all. That fallback is the CLI's, and this is the decision the two share.

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.

Find every CiFile declared on a build instance. A fan-out file is resolved here — its jobs are expanded from the build's targets — so the returned files render the same whether they fan out or not.

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.

How a downloaded artifact is treated: "raw" is the binary itself, an ArchiveFormat is unpacked and one path taken from inside.

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

The context an effect body receives: the target's own context, plus which effect this is and whether it has been driven before.

The body of a declared effect (see TargetBuilder.effect).

The durable intent-and-completion row for one of a target's effects.

There is no idempotency key here. An effect is identified by where it sits — the run, the target, and its declared name — which the record already spells out structurally, so a key would be a second spelling of the same fact and a place for a secret to end up.

Where one declared effect has got to (see .effect(...)).

pending is the load-bearing one: it means the intent was committed and the body may or may not have run. A process that dies mid-effect leaves exactly that, which is what tells a later resume to drive it again.

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.

Escape a value interpolated into the body of a GitHub Actions workflow command (::error::<data>).

A workflow command is terminated by the end of its line, so a value carrying a newline continues into what the runner parses as a *fresh* command. A target's failure message embeds a subprocess's stderr verbatim, which is not ours to trust: a tool that writes ::stop-commands:: on a line of its own would otherwise suspend the runner's command processing, and one that writes ::error:: would forge an annotation. Percent-encoding is the escape the Actions spec defines for exactly this, and % is encoded first so the encoding cannot be spoofed by a literal %0A in the input.

Neutralise workflow commands in text that is *printed as itself* on a stream the GitHub Actions runner parses — a failure message, a target name, a summary row — rather than interpolated into a command's body.

escapeData is the wrong tool there. It answers the same threat, but by encoding every newline, which would fold a multi-line compiler dump into one unreadable %0A-joined line: correct, and useless to the person reading the log. This keeps the text as it was written and disarms only the two sequences the runner acts on.

Both forms are covered, because the runner accepts both. A line whose first non-blank characters are :: opens a command, and leading whitespace is trimmed before that test, so indenting the text defends nothing. The legacy ##[command] form is recognised *anywhere* in a line, so it needs no newline to reach at all.

"Blank" is the runner's idea of it, not this language's. The two sets differ by exactly one character in the direction that matters: NEXT LINE (U+0085), which the runner trims and \s does not match. It is not a line terminator for the reader the runner uses, so it travels inside a line and disappears only when the command is parsed, which would let :: reach the front of a line that looked indented here. It is matched explicitly for that reason.

Ordinary output is returned unchanged; only text that would have been executed as a command comes back visibly encoded.

escapeLine, applied only when something is parsing this process's output for workflow commands.

The condition is not a security gate — the runner parses every line a step writes, whatever this process believes about its own style. It is a readability one: escapeLine leaves ordinary text alone, but a compiler dump that legitimately begins a line with :: would come back encoded, and on a developer's terminal that is noise protecting against nothing.

It exists so the decision has one implementation. It was written out at more than a dozen call sites, in three shapes that had already drifted apart — two asking the style, one asking the environment — which is how a site gets added without it.

Escape a value interpolated into a workflow command's property list (::error title=<property>::). Properties are comma-separated and colon-terminated, so those two characters need encoding on top of what escapeData handles.

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.

Why a force was refused. Each maps to a message naming the target, so an operator learns which rule stopped them rather than that "it failed".

What an operator may force a target to, without running it.

Options for forceTarget.

The result of a forceTarget call.

Record an operator's forced outcome for one target of a run.

The write is a compare-and-swap, retried against a re-read record, so two operators forcing different targets at once cannot lose each other's decision. Every refusal is re-checked on each attempt, because the thing that beat us to the record may be the target settling.

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.

Thrown when a recovery path is handed a run that a different build owns: the run's recorded origin and this process's disagree.

A sweep treats it as "not mine" and moves on rather than counting a failure, the same way it treats a run another process has already resumed. A command that named one run reports it, because the operator asked about a run that is not this build's to touch.

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, 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.

A relative pattern is resolved against cwd and its matches are returned relative to it. An absolute pattern (a leading /, or a C:-style drive) names its own root: cwd plays no part and the matches come back absolute.

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 action a CiHardenRunner is generated from when pins are resolved.

A held lease. Release it when the work it covers is over.

One live lock, as reported by "./store.ts".StateStore.listLocks — the key, who holds it, and when it lapses if the holder disappears.

Deliberately not the stored record: the acquisition token is the holder's proof of ownership, and a read-only listing has no business handing it out.

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. A restored archive cannot name a path outside the workspace, cannot carry a link or directory entry, and is refused if the path it would land on passes through a symlink the workspace already holds — so a poisoned store cannot write outside the workspace (see restoreOutputs). An artifact larger than HttpCacheStoreOptions.maxArtifactBytes is refused before it is buffered, and restoreOutputs separately bounds what it decompresses to.

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.

Who a run is attributed to for a reader that wants its *owner* rather than its last writer: the recorded initiator, else the actor.

The fallback is not a guess — on a record written before the initiator existed, and on any run that was never resumed, actor still holds exactly the value the initiator would have been stamped with.

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.

The refusal for a request that presented a token which did not hold up — expired, wrong signature, wrong audience.

Distinct from UNAUTHORIZED on purpose: OAuth 2.1 §5.3.1 says a challenge SHOULD NOT carry error information when the request had no credentials at all, because there is nothing yet to have been wrong. Sending invalid_token to a client that simply has not logged in tells it its stored token was rejected, which is a different and misleading thing.

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

Broader than detectCiHost(env) !== "local", which answers only whether the host is one of the four Zuke names: a system it has no specific support for is still CI, and this says so.

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.

The locks store holds, or a friendly failure when the backend cannot enumerate them.

An empty array reads as "nobody holds anything", which is the worst possible answer to give someone looking at a wedged resource, so a store with no StateStore.listLocks says so rather than answering.

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.