@zuke/engine

`@zuke/engine` — the engine for a build another process hosts. An SDK in

Symbols

ConfigureParams

interface

interface ConfigureParams

What build.configure tells the worker once the parameters have resolved, before build.onStart and before any body: each parameter's value in its CLI form, or null when unset. The run's id and dry-run flag travel with every target.run instead, since the build's own onStart has neither.

Member	Signature	Doc
`parameters`	`parameters: Readonly<Record<string, string \| null>>`	Each parameter's resolved value in its CLI form, or null when unset.

Duration

type

type Duration = string | number

A duration as the wrappers take it: "5m" or milliseconds.

HookName

type

type HookName = unknown

The hooks a worker may implement, named as the build.* methods are.

importTool

function

async function importTool(pkg: string, version: string): Promise<Record<string, unknown>>

The default ToolResolver: a dynamic import of the release from JSR, or from the workspace when it holds that version of the package.

LateSettings

interface

interface LateSettings

What target.settings answers for one target: the sections it declared.

Member	Signature	Doc
`lock?`	`lock?: LockSpec`	The lock, when the target declared one.
`waitsFor?`	`waitsFor?: WaitSpec`	The wait gate, when the target declared one.
`validateDuring?`	`validateDuring?: ValidateDuringSpec`	The interval checks, when the target declared them.

LockSpec

interface

interface LockSpec

A cross-run lock, as LockSettings configures it.

Member	Signature	Doc
`key`	`key: string`	The lock's key.
`ttl?`	`ttl?: Duration`	How long the lock may be held.
`waitUpTo?`	`waitUpTo?: Duration`	How long to wait for a held lock before giving up.
`pollEvery?`	`pollEvery?: Duration`	How often to poll a held lock.
`holdForRun`	`holdForRun: boolean`	Keep the lock until the run ends rather than until the target does.

Manifest

interface

interface Manifest

The build as the worker describes it in reply to build.describe.

Member	Signature	Doc
`name`	`name: string`	The build's name.
`targets`	`targets: unknown`	The targets, in declaration order.
`parameters`	`parameters: unknown`	The parameters, in declaration order.
`groups`	`groups: unknown`	The groups.
`hooks`	`hooks: ManifestHooks`	The hooks the worker implements.
`config`	`config: ManifestConfig`	Build-wide settings.
`ci`	`ci: unknown`	The CI files the build declares, for `generate-ci`.

ManifestCi

interface

interface ManifestCi

One CI file the build declares.

Member	Signature	Doc
`name`	`name: string`	The field the file is declared on, which names its default path: `releaseWorkflow` writes `.github/workflows/release.yml`.
`provider?`	`provider?: CiProvider`	The provider to render for; GitHub when omitted.
`path?`	`path?: string`	The output path, overriding the one the name implies.
`pipeline?`	`pipeline?: CiPipeline`	The pipeline-level fields, and the jobs unless `invokes` or `fanOut` supply them.
`invokes?`	`invokes?: unknown`	The targets to run as jobs, bare or with the runner's adjustments.
`fanOut?`	`fanOut?: boolean \| FanOutOptions`	One job per target in the graph; the options without a command, which stays the launcher.
`pins?`	`pins?: Readonly<Record<string, CiUses>>`	Pinned action references by action name: what a `pins` resolver answers.

ManifestCiInvocation

interface

interface ManifestCiInvocation

An invoked target as the manifest names it, and the targets it runs after.

Member	Signature	Doc
`target`	`target: string`	The target the job runs.
`after?`	`after?: unknown`	Extra `needs:` edges, by target name.

ManifestConfig

interface

interface ManifestConfig

Build-wide settings.

Member	Signature	Doc
`deadline?`	`deadline?: string \| number`	The run's deadline, as a duration or milliseconds.
`unforceable`	`unforceable: unknown`	Targets `--force` may never re-run.

ManifestGroup

interface

interface ManifestGroup

A parallel batch of targets.

Member	Signature	Doc
`name`	`name: string`	The group's field name.
`members`	`members: unknown`	The targets in it.

ManifestHooks

interface

interface ManifestHooks

Which build hooks the worker implements; the engine calls only those.

Member	Signature	Doc
`onStart`	`onStart: boolean`	`build.onStart`, before the first target.
`onTargetStart`	`onTargetStart: boolean`	`build.onTargetStart { target }`, before each target.
`onTargetEnd`	`onTargetEnd: boolean`	`build.onTargetEnd { target, status }`, after each target settles.
`onFinish`	`onFinish: boolean`	`build.onFinish { ok }`, before `run.exit`.

ManifestParameter

type

type ManifestParameter = ManifestParameterBase & unknown

One build parameter as the worker describes it, by kind.

ManifestParameterBase

interface

interface ManifestParameterBase

What is common to every parameter kind.

Member	Signature	Doc
`name`	`name: string`	The field name the build declares it under.
`description`	`description: string`	The `--help` description.
`required`	`required: boolean`	Whether a value must be supplied.
`array`	`array: boolean`	Whether the value is a comma-separated list.
`secret`	`secret: boolean`	Whether the value is masked and redacted.
`flag?`	`flag?: string`	The CLI flag, when it is not derived from the name.
`env?`	`env?: string`	The environment variable, when it is not derived from the name.

ManifestRetry

interface

interface ManifestRetry

Extra attempts after a failed body, and the pause between them.

Member	Signature	Doc
`times`	`times: number`	How many more times to run the body after it fails.
`delayMs`	`delayMs: number`	Milliseconds to wait between attempts.

ManifestTarget

interface

interface ManifestTarget

One target as the worker describes it.

Member	Signature	Doc
`name`	`name: string`	The target's name, also its CLI name.
`kind`	`kind: target \| service`	A plain target with a body, or a service the engine starts and stops.
`ready`	`ready: boolean`	Whether the worker answers `service.ready` for this service.
`readyTimeoutMs?`	`readyTimeoutMs?: number`	How long the readiness probe may take before the service fails.
`description`	`description: string`	The `--list` description.
`dependsOn`	`dependsOn: unknown`	Names of targets this one depends on; each must be declared earlier.
`unlisted`	`unlisted: boolean`	Hide from `--list` and `--help`.
`inputs`	`inputs: unknown`	Input paths whose contents key the cache.
`outputs`	`outputs: unknown`	Output paths that must exist for a cache hit.
`produces`	`produces: unknown`	Artifact paths this target produces.
`retry`	`retry: ManifestRetry`	The retry policy.
`timeoutMs?`	`timeoutMs?: number`	Per-attempt timeout in milliseconds, if any.
`before`	`before: unknown`	Soft ordering: run before these targets when both are planned.
`after`	`after: unknown`	Soft ordering: run after these targets when both are planned.
`triggers`	`triggers: unknown`	Targets pulled in and run after this one.
`proceedAfterFailure`	`proceedAfterFailure: boolean`	Keep the build running after this target fails.
`always`	`always: boolean`	Run even after the build has failed.
`dryRunnable`	`dryRunnable: boolean`	Run the body under `--dry-run` too.
`requires`	`requires: unknown`	Parameters that must resolve before this target runs.
`onCancel?`	`onCancel?: string`	The compensation target to run when the run is cancelled after this one succeeded.
`onFailure?`	`onFailure?: string`	What this target's failure does: `fail`, `cancel-run`, or a compensation target.
`condition`	`condition: boolean`	Whether the engine must ask `target.condition` before running this target.
`cacheKey`	`cacheKey: boolean`	Whether the engine must ask `target.cacheKey` when fingerprinting this target.
`lock`	`lock: boolean`	Whether `target.settings` answers a `lock` section for this target.
`waitsFor`	`waitsFor: boolean`	Whether `target.settings` answers a `waitsFor` section for this target.
`validateDuring`	`validateDuring: boolean`	Whether `target.settings` answers a `validateDuring` section for this target.

materialize

function

function materialize(manifest: Manifest, runner: TargetRunner): unknown

Build the class. Dependencies must be declared before the targets that use them, mirroring the forward-reference rule of a zuke.ts build; a violation throws from the constructor with the offending target named. The ordering hints, triggers, compensations and group members may name any target.

parseManifest

function

function parseManifest(value: unknown): Manifest

Validate a build.describe result.

parseToolCall

function

function parseToolCall(value: unknown): ToolCall

Validate a tool.call request's params.

PROTOCOL_VERSION

const

const PROTOCOL_VERSION: 1

The protocol version this engine speaks.

sdkCommand

function

function sdkCommand(configText: string, where: string): string[]

Read sdk.command from the zuke.json text, naming what is wrong if not.

SpawnBase

interface

interface SpawnBase

The worker's environment and working directory: the base of every spawn.

Member	Signature	Doc
`env`	`env: Readonly<Record<string, string>>`	The environment the wrapper's command inherits, under the caller's overrides.
`cwd`	`cwd: string`	The working directory the command runs in, unless a setter moves it.

TargetRunner

interface

interface TargetRunner

What a materialised build needs from its host.

Member	Signature	Doc
`configure`	`configure: unknown`	Tell the worker the resolved parameter values.
`hook`	`hook: unknown`	Call a flagged build hook.
`condition`	`condition: unknown`	Ask whether a target's condition holds.
`cacheKey`	`cacheKey: unknown`	Ask for a target's extra cache key.
`settings`	`settings: unknown`	Ask for a target's late settings.
`waitCheck`	`waitCheck: unknown`	Ask whether a `resumeWhen` gate holds.
`validate`	`validate: unknown`	Run one `validateDuring` check.
`serviceStart`	`serviceStart: unknown`	Start a service; answers its handle.
`serviceReady`	`serviceReady: unknown`	Ask whether a service is ready.
`serviceStop`	`serviceStop: unknown`	Stop a service.
`runTarget`	`runTarget: unknown`	Run the named target's body; reject when it fails.
`finish`	`finish: unknown`	Tell the worker the run is over.

ToolCall

interface

interface ToolCall

A tool.call request: a wrapper's task the engine runs on the worker's behalf, with the worker's environment and directory under its settings.

Member	Signature	Doc
`target`	`target: string`	The target whose body or phase is asking, for attribution and cancellation.
`package`	`package: string`	The wrapper's name after `@zuke/`, e.g. `docker`.
`version`	`version: string`	The wrapper's exact release, e.g. `1.4.0`.
`tasks`	`tasks: string`	The task object the wrapper exports, e.g. `DockerTasks`.
`task`	`task: string`	The task on it, e.g. `build`.
`args`	`args: unknown`	The task's arguments as JSON. An argument that is an object with a single `configure` key is a settings lambda as data: an ordered list of `[setter, [arguments]]` pairs the engine applies to the task's settings.

ToolResolver

type

type ToolResolver = unknown

Resolves a wrapper release to its module: what tool.call imports.

ValidateDuringSpec

interface

interface ValidateDuringSpec

Checks run on an interval while the body runs, as ValidateDuringSettings configures them.

Member	Signature	Doc
`every?`	`every?: Duration`	The interval.
`checks`	`checks: unknown`	The checks' names, each answered by `target.validate`.

WaitSpec

interface

interface WaitSpec

A wait gate, as WaitSettings configures it.

Member	Signature	Doc
`on`	`on: WaitTriggerSpec`	The trigger.
`timeout?`	`timeout?: Duration`	How long to wait before the timeout disposition applies.
`onTimeout?`	`onTimeout?: string`	`fail`, `cancel-run`, or a compensation target.

WaitTriggerSpec

type

type WaitTriggerSpec = unknown | unknown

What a wait gate waits on.

WorkerHost

class

class WorkerHost

The worker host. Start one with WorkerHost.start.

Member	Signature	Doc
`sdk`	`sdk(): string`	The SDK the worker announced itself as.
`start`	`start(options: WorkerOptions): Promise<WorkerHost>`	Spawn the worker and wait for its `hello`.
`describe`	`describe(): Promise<Manifest>`	Ask the worker to describe its build; a replacement must match it.
`configure`	`configure(params: ConfigureParams): Promise<void>`	Tell the worker the resolved parameters; a replacement gets the same.
`hook`	`hook(name: HookName, params: unknown): Promise<void>`	Call a build hook the manifest flagged and wait for it to settle.
`condition`	`condition(target: string): Promise<boolean>`	Ask whether the named target's condition holds.
`settings`	`settings(target: ManifestTarget): Promise<LateSettings>`	Ask for the late settings a target declared, once parameters resolved.
`waitCheck`	`waitCheck(target: string): Promise<boolean>`	Ask whether a `resumeWhen` gate's predicate holds now.
`validate`	`validate(target: string, check: string): Promise<void>`	Run one of a target's `validateDuring` checks; rejects with its message.
`cacheKey`	`cacheKey(target: string): Promise<string>`	Ask for the named target's extra cache key.
`runTarget`	`runTarget(name: string, ctx: TargetContext): Promise<void>`	Run one target's body in the worker, serving the calls it makes until it settles. Rejects with the worker's message when the body fails.
`serviceStart`	`serviceStart(target: string): Promise<string>`	Start a service in the worker; its start phase may `exec`.
`serviceReady`	`serviceReady(target: string, handle: string): Promise<boolean>`	Ask whether a started service is ready.
`serviceStop`	`serviceStop(target: string, handle: string): Promise<void>`	Stop a started service; its stop phase may `exec`.
`finish`	`finish(code: number, suspended?: boolean): Promise<void>`	Tell the worker the run is over, or suspended at a gate, wait for it to exit, release everything. The run ends, not the host: the next request (an MCP server runs build after build in one process) spawns a fresh worker, described and configured anew.
`close`	`close(): Promise<void>`	End the host for good: a pre-warm in flight is awaited and its worker stopped with the current one, and none is spawned after. A one-shot run needs no call; it ends with its process.
`kill`	`kill(): void`	Kill the worker outright, and whatever its service phases spawned.

WorkerOptions

interface

interface WorkerOptions

How the host starts its worker.

Member	Signature	Doc
`command`	`command: unknown`	The worker's argv, from `zuke.json`'s `sdk.command`.
`cwd`	`cwd: string`	The directory to start the worker in.
`connectTimeoutMs?`	`connectTimeoutMs?: number`	How long to wait for the worker's `hello` before giving up.
`graceMs?`	`graceMs?: number`	How long a cancelled body may take to settle before the worker is killed.
`prewarm?`	`prewarm?: boolean`	Spawn and describe the next worker as soon as a run ends, so the next run of a long-lived host (the MCP server, which runs build after build in one process) finds one up instead of paying the spawn inside its request. Off by default: a one-shot run has no next run. A pre-warm that fails is dropped, and the next run spawns its own worker and meets the error.
`tools?`	`tools?: ToolResolver`	How a `tool.call` finds the wrapper release it names: a dynamic import of `jsr:@zuke/<package>@<version>` by default, which the workspace resolves locally for a member's own version. A test hands in a module of its own.