A build is a class that extends Build. Each target is a class field\ncreated with target() and made runnable with await run(MyBuild) at the\nbottom of zuke.ts (no import.meta.main guard — run no-ops on import).
import { Build, run, target } from \"jsr:@zuke/core\";\nimport { DenoTasks } from \"jsr:@zuke/deno\";\n\nclass CI extends Build {\n lint = target()\n .description(\"Lint sources\")\n .executes(async () => {\n await DenoTasks.lint();\n });\n\n test = target()\n .description(\"Type-check and test\")\n .dependsOn(this.lint)\n .executes(async () => {\n await DenoTasks.test((s) => s.allowAll().coverage(\"cov_profile\"));\n });\n\n // A field named `default` runs when no target is named on the CLI.\n default = target().dependsOn(this.test).executes(() => {});\n}\n\nawait run(CI);\nthis.<field> references, never strings.\n.dependsOn(this.lint), not .dependsOn(\"lint\") — so renames and typos are\ncompile-time errors.undefined and is reported\nas an error (TypeScript also flags it, TS2729). Order fields so\ndependencies come first.llms.txt's\n## Packages catalogue (raw:\nhttps://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt) and the\npackage table in references/cheatsheet.md are\nthe only ways to answer \"does a @zuke/<tool> wrapper exist for this CLI?\" —\nper-package deno doc jsr:@zuke/<pkg> only describes a package whose name\nyou already know; it cannot tell you a wrapper exists. Whatever runs in an\n.executes(...) body drives an external tool through its namespaced *Tasks\nobject, configured with a settings lambda that mirrors the real CLI's\nflags — DenoTasks, NpmTasks, DockerTasks, GitTasks, and 30+ more —\nnever a raw Deno.Command or shell string. jsr:@zuke/cmd (CmdTasks.exec)\nor the $ shell from jsr:@zuke/core/shell is the last resort, reached\nfor only once the catalogue confirms no typed wrapper exists — using it for a\ntool that has a @zuke/<tool> package is a bug, not a style choice: it\ndiscards typed flags, argv purity, and tool resolution. (If a build delegates\nits side effects to your own tested modules behind injected clients, the\nwrapper rule still governs whatever those modules run in the target body.)service(), a .forEach() fan-out, a .waitsFor() gate, or a\ntarget declaring only .effect(...). Otherwise set .executes(...); it may\nbe sync or async, and its return value is ignored —\n.executes(() => DenoTasks.lint()) is fine as-is; never wrap a single\nwrapper call in an async block just to discard its result.Before calling any task or settings method, confirm the real shape — but first\nconfirm a wrapper exists at all: deno doc needs a package name to target, so\nit cannot answer \"does one exist for this tool?\"; only the catalogue\n(llms.txt's ## Packages list or the cheatsheet table below) can.
deno doc jsr:@zuke/<package> (e.g. deno doc jsr:@zuke/deno). It resolves\nthe version the project actually has installed, so it cannot describe an API\nthat version lacks.llms-full.txt (index: llms.txt) — at the repo root in\nthe Zuke repo itself. From a consumer repo, fetch\nhttps://raw.githubusercontent.com/zuke-build/zuke/master/llms-full.txt\n(index: https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt).\nBoth track master, so they can document symbols that are merged but not yet\nin any published release. Use them for breadth — which packages and tasks\nexist — and confirm a signature with deno doc before relying on it.references/cheatsheet.md next to this file —\nread it when wiring targets, then verify specifics against the sources above.zuke.ts to learn the targets already declared and their\norder.*Tasks object and settings\nmethods (cheatsheet → deno doc / llms-full.txt).this.<field>../zuke --list shows it; ./zuke <target> --dry-run previews the\nplan; ./zuke <target> runs it.group() + .partOf(this.group) run members\nconcurrently; depend on the group to wait for all of them.this.release.publish.service() models a process that must stay running\nwhile dependents execute (dev server, database, mock API). Declared and\ndepended on like a target, but with a .start(...) / .readyWhen(...)\nlifecycle instead of .executes(...); the executor starts it, waits until\nready, then stops it in a finally so it never leaks. See the cheatsheet..executes((ctx) => …) — with ctx.runId, ctx.target, ctx.signal (an\nAbortSignal fired when the run is cancelled; a plain $`…` in the body\nis SIGTERM'd automatically), ctx.state, and ctx.dryRun. Zero-argument\nbodies keep working unchanged. Cancel a run programmatically by passing\n{ signal } to execute. See the cheatsheet..inputs(...) / .outputs(...) make a target incremental. Add a\nremote store to share results across machines (fresh CI, teammates);\n--affected runs only targets changed since a git base; --no-cache /\n--no-remote-cache bypass them. A restore is confined to the target's\ndeclared .outputs(...) (and never .git/.zuke); a refused archive is a\ncache miss with a warning, not a failure. A cancelled run keeps its cache\nunless a compensation actually rolled something back.StateStore so it survives the process — turn it on with --state,\nZUKE_STATE_DIR / ZUKE_STATE_URL, or override stateStore(). Every\nZUKE_*_URL backend must be https: (loopback exempt;\nZUKE_ALLOW_INSECURE_URL=1 opts out). In a body, ctx.state.set({ … }) /\nctx.state.get() records per-target metadata (JSON, never secrets —\nsecret parameters and redacted values are excluded). Inspect persisted runs\nafterwards with zuke runs list (filter by\n--status/--target/--since/--limit) and zuke runs show <id> (--json\non both). Prune old ones with zuke runs prune --keep <age> --keep-last <n>\n(only terminal runs; never suspended/running). A run whose process is killed\nis picked up by zuke resume --check, which reaps it — its lease tells a dead\nholder from a slow one — and resumes it in the same sweep. A process that\nmerely looked dead and then finds its lease taken over stops, running no\ncompensations and settling nothing: the run is the new holder's now.\noverride deadline() gives a run a wall-clock budget (\"45m\", or\nmilliseconds) that survives suspension; an abandoned run found past it is\nsettled failed with its compensations instead of resumed. On a shared\nstore, set ZUKE_BUILD_ID (or rely on GITHUB_REPOSITORY) so each build only\nrecovers its own runs — a resume runs this build's bodies against whatever\nrecord it is given, and a templated zuke.ts looks identical to the shape\nchecks. See the cheatsheet..lock((s) => s.lockKey(...).withTtl(\"4h\")) — a settings\nlambda — gives a target an exclusive claim across runs/machines; a second run\nwanting the same key fails with a LockConflictError naming the holder, or\nqueues when the target adds .waitUpTo(\"30m\") (paced by .pollEvery). The\nlambda runs after params resolve, so the key can read this.<param>.value.\nThe lock releases when the target settles and expires after the TTL if the\nholder is killed. Needs a state store (a build with .lock() enables the\nfilesystem store by default). See the cheatsheet..waitsFor((s) => s.on(externalSignal(\"approved\")).timeout(\"72h\")) makes a\ntarget a gate with no body: the run proceeds past it only when the trigger\nis satisfied, otherwise it suspends (state saved, exits 0) to be resumed\nlater in a fresh process. Triggers: externalSignal(name) (payload read via\nctx.signals) and resumeWhen(predicate). Continue it with\nzuke resume <id> --signal <name> [--data <json>] (or --check for predicate\nwaits/timeouts) — exactly-once, re-running only the not-yet-succeeded targets.\nNeeds a state store. See the cheatsheet / docs/orchestration.md..onCancel(() => this.rollback) registers a\ncompensation that runs iff this target succeeded when the run is later\ncancelled — compensations run in reverse order, and the compensation body's\nctx.state exposes the original target's persisted metadata (so a rollback\nreads what the deploy recorded). Cancel with zuke cancel <id> (or Ctrl-C, or\nthe MCP cancel_run tool). Idempotent; a timed-out wait can route its\nonTimeout here (\"cancel-run\" or a named target). Needs a state store. See\ndocs/orchestration.md..effect(name, fn) records the intent to run fn\nbefore it runs, so a resume re-drives an effect a dead process left owed.\nEffects run after the body, in declaration order; a target may declare effects\nand no body. The guarantee is at-least-once, so write bodies that tolerate\na repeat (an upsert, not an append), and read what the effect acts on from\nctx.state rather than looking up \"the current value\" — a re-drive happens\nlater, against a world that moved on. Needs a state store (enabled\nautomatically). See the cheatsheet / docs/orchestration.md..forEach(() => this.repos.value, (repo) => ({ checks: target()…, deploy: target()… }), (s) => s.concurrency(3).continueOnItemFailure())\nruns the same pipeline over a runtime list — items concurrent, each item's\nstages sequential. Sub-targets are materialised at run time\n(parent[item].stage), each a first-class row in the summary and the run\nrecord; continueOnItemFailure() isolates a failed item. An .onCancel(...)\non a fan-out stage runs per item on cancel (item-scoped ctx.state, reverse\norder). See docs/orchestration.md.parameter(\"...\") (with .number() / .boolean() /\n.options(...) / .secret() / .required()), read as this.x.value, gated\nwith .requires(this.x). .array() composes and comes last:\n.options(...).array() validates each element, .number().array() →\nnumber[], and a required list is .required().array() (required before\narray — .array().required() does not typecheck).parameter(...).secret().from(source) sources a\nvalue at run time (e.g. execSecret(...) shelling out to a secret CLI) and\nredacts it from all of Zuke's output. See the cheatsheet.ToolTasks.install((s) => …) / toolchain((t) => …)\nfetch pinned, checksum-verified release binaries so a build is hermetic, and\nt.npm({ name, version, bin? }) / ToolTasks.npm(...) provision a\nversion-pinned, cached npm-registry package (needs npm on PATH); hand the\nreturned path to a wrapper's .toolPath(...). In a Node monorepo, resolve a\nwrapper's binary from node_modules/.bin npx-style instead —\n.fromNodeModules() on the settings (or ZUKE_TOOL_RESOLUTION=node_modules\nrepo-wide) walks up for the local shim and falls back to PATH; .fromPath()\nforces PATH and an explicit .toolPath(...) always wins. See the cheatsheet /\ndocs/tools.md.cicd({ provider: \"github\" }) generates and verifies the\nworkflow YAML from the build.zuke mcp serves the build over MCP so\nan AI client can list, inspect, and (with --allow-run) run targets — on\nstdio, or over HTTP with --http <host:port> (loopback by default; a\nnon-loopback bind needs a ZUKE_MCP_TOKEN bearer token). With a state store\nit also exposes list_runs/show_run (+ signal_run, resume_check and\ncancel_run). Tier access with --allow-run=<globs> (an allow-list over\ninvocation — invoking a target runs its dependencies, and the read tools\nnarrow to the allow-listed targets' closure), --protect <globs> +\nZUKE_OPERATOR_TOKEN (enforced over a run's whole plan, so a protected\ntarget reached as a dependency still needs the token), and\n--confirm-destructive; mark inspect-only targets .readOnly().\nMutating/denied calls are audited — read the trail on the host with\nzuke runs show mcp-audit; it is deliberately not readable over MCP. A\nregistry-backed server (zuke register then zuke mcp --registry)\ninstead serves every registered pipeline live, each as a\nrun:<buildId>:<target> tool that takes the build's declared parameters\n(secrets excluded, validated, forwarded to the spawn) — see the cheatsheet.\nBecause the registry names where a build launches from, a descriptor with a\nremote entry module is refused unless its origin is in\nZUKE_REGISTRY_LAUNCH_HOSTS; zuke register writes a local module, so this\nonly affects a hand-authored or second-party entry. For a shared, multi-user\nendpoint, override mcpIdentity() resolves a trusted caller per request\nfrom an authenticating proxy's header (it overrides the client-reported actor\nand flows to the audit trail, run records, and lock holders; a throwing hook\nrejects the request).@zuke/ai): gate a target on a structured LLM\nreview of the diff (securityReviewer(...) etc. via .validateBefore), or\nattach aiFixer(...) with .recoverWith(...) so a failing target is\ndiagnosed and (opt-in) auto-fixed, with a committable PR suggestion. Override\nrecoverWith() on the build to apply one fixer to every target. A reviewer\ncan go deeper and hold a discussion: .conventionsFile(\"AGENTS.md\") (judged\nagainst the project's rules, read from the diff base), .fileContext() (whole\nchanged files, not bare hunks), .verify() (adversarial re-check of every\nfinding), and .discussion() (maintainers refute a finding by replying with\nits id — or, with .discussion((d) => d.threads()), by replying in the\nfinding's own line-anchored review thread; accepted dismissals persist instead\nof resurfacing, including when the model rewords the finding — only\nplatform-verified maintainer comments ever reach the model, on GitHub, GitLab,\nAzure DevOps and Bitbucket alike). See the cheatsheet's AI section.@zuke/gh): in a .waitsFor(...)\ngate, s.on(githubWorkflow((g) => g.repo(\"o/r\").workflow(\"e2e.yml\")))\ndispatches a workflow in another repo and suspends until it finishes; read the\nper-job result with readWorkflowResult(ctx.stateOf(\"<gate>\")). Correlates by\na run-name: marker by default, or .correlate(\"created-window\") for a\nworkflow you can't modify; fails fast (.discoveryTimeout(...)) if the run\nnever correlates. The dispatched workflow has a contract: declare the\nmarker input (zuke_marker, or rename via .markerInput(...)), echo it as\nits entire run-name: (equality, not substring), and receive any of its\nrequired: true inputs via .inputs(...) — see the cheatsheet's\nreceiving-workflow contract. Triggers are extensible — write your own against\nthe exported WaitTrigger/WaitContext.@zuke/otel): register otel((s) => s.endpoint(…))\nas a plugin (run(MyBuild, { plugins: [otel(…)] })) to ship run/target spans\nand zuke.run.started / zuke.run.suspended / zuke.runs counters as\nOTLP/HTTP JSON. Needs a state store; the trace id is derived from the run id,\nso a suspend/resume across processes is one trace. Config falls back to the\nstandard OTEL_* env vars, and it is inert with no endpoint. Dependency-free.