Typed build automation for Deno and agents

A code-first, strongly-typed build automation system for Deno & TypeScript. Your build and your CI are one typed file — and your agent can run it.

Zuke lets you define a build as a TypeScript class. Each target is a class field; targets reference each other by this.x, not by string, so a rename is a refactor and a typo is a compile error. From that one file Zuke resolves the dependency graph, runs it in order, generates your CI YAML, and exposes the whole thing to AI agents as typed tools. Inspired by NUKE for .NET. Zero runtime dependencies.

Five minutes to a typed build

deno install -A -g -n zuke jsr:@zuke/cli   # 1. the CLI, once
zuke setup                                  # 2. scaffold zuke.ts + the ./zuke launcher
./zuke                                      # 3. run it
./zuke generate-ci                          # 4. write .github/workflows/ci.yml from the build

Step 4 needs one line in the build. Here is the whole file after you have replaced the scaffolded sample target with real work:

import { Build, cicd, run, target } from "jsr:@zuke/core";
import { DenoTasks } from "jsr:@zuke/deno";

class MyBuild extends Build {
  ci = cicd({ provider: "github" }); // ← the pipeline, generated and verified

  lint = target().executes(() => DenoTasks.lint());

  test = target()
    .dependsOn(this.lint)
    .executes(() => DenoTasks.test((s) => s.allowAll().coverage("cov")));

  default = target().dependsOn(this.test).executes(() => {});
}

await run(MyBuild);

./zuke test runs lint then test. ./zuke --list prints every target with its description and dependencies. ./zuke graph --output=html draws the graph. And the workflow file is regenerated on every run and verified on CI, so the YAML can never drift from the build.

Already have package.json scripts or a Makefile? zuke import turns them into a zuke.ts with a target per script. Details, the launcher, and a longer first build: Getting started.

Prefer to poke at something real? examples/ holds five cloneable projects — a Deno library gate, a generated-CI-only project, a Node app, a library release routine, and a shell script turned into targets — each runnable from its own folder with deno run -A zuke.ts.

Three short recipes cover what a small project wants first: replace your shell scripts, generate your CI and stop editing YAML, and release a small library.

Why Zuke

• Typed, refactor-safe dependencies. You wire targets together with this.clean, not "clean". Rename a target and every reference moves with it; a typo is a compile error, not a runtime surprise.
• Never write CI YAML again. Declare the pipeline in the build with cicd({ provider: "github" }) — the provider is the only required field — and Zuke generates GitHub Actions, GitLab CI, Azure Pipelines, or Bitbucket YAML. fanOut: true turns every target into its own job wired by needs: edges that mirror dependsOn. It is regenerated on every run, and generate-ci --check fails CI when the committed file has drifted. You run the exact same targets locally with ./zuke ci before you push.
• Let your agent run the build. ./zuke mcp serves the build over the Model Context Protocol: an agent lists the targets, reads the graph, and runs one with typed parameters, instead of guessing npm run what?. zuke setup --mcp writes the client registration on day one. ./zuke --list --json and the generated llms.txt are the static counterparts, and the agent skills teach Claude Code, Codex, and Gemini CLI to write a zuke.ts the right way.
• Just TypeScript. Build logic is ordinary async functions with full editor support — no bespoke DSL. The $ tagged template from @zuke/core/shell runs processes with sane defaults and is injection-safe, so it also replaces the scripts/*.sh nobody dares touch.
• A typed wrapper for every tool. 58 packages: a tiny core, the CLI, and a *Tasks object per tool — Deno, npm, pnpm, Bun, Docker, Kubernetes, Terraform, Vite, Playwright, GitHub, Claude Code, and the rest — whose settings lambdas mirror the real flags. See Packages.
• Small and explicit. Discover targets, build a graph, sort, run. No magic, and no plugins to learn for a basic build — the plugin contract is there once you want one.

See How Zuke compares for a capability matrix against deno task, npm scripts, Make, Nx, Turborepo, and Dagger.

Who's using Zuke

Teams running Zuke in production:

Using Zuke at your company? We'd love to list you — open a pull request adding your logo to assets/users/ and an entry to this section, or say hello in an issue and we'll add it for you.

Install

Zuke runs on Deno and is imported straight from JSR — there is nothing else to install. By default the scaffolded ./zuke launcher (and zuke.ps1 on Windows) bootstraps a pinned, checksum-verified Deno on first use, so a checkout needs nothing installed up front — it is the same script this repository runs on, zuke / zuke.ps1. zuke setup asks; --no-bootstrap-deno scaffolds a launcher that uses the Deno on your PATH and fails closed without one, for a project that must never download a tool from its build entry point.

deno install -A -g -n zuke jsr:@zuke/cli   # the CLI: setup, import, doc
zuke setup                                  # or: deno run -A jsr:@zuke/cli setup
zuke setup --mcp                            # …and register the build's MCP server for your agent
zuke import                                 # migrate package.json scripts / a Makefile instead

[!NOTE] Maturity. Every one of the 58 packages is 1.x and follows full semver — @zuke/core, the @zuke/cli command, and all the tool wrappers. A minor or patch release never breaks a public symbol; a breaking change bumps the major. See Versioning & compatibility. The npm scope @zuke is not controlled by this project — install from JSR, not npm.

[!NOTE] Built with AI. Much of Zuke — code, tests, and docs — was written with AI assistance, then reviewed, type-checked, and tested in CI. Sharing how it was made so you know what you're getting.

GitHub Actions

The Zuke Build action is the whole prelude a Zuke job needs — it hardens the runner, checks the repository out, and runs a target, in one step:

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: zuke-build/zuke@v1
        with:
          target: ci

Pin the full commit SHA rather than the moving v1 tag when you commit it, as you would any other action. Zuke's own six workflows all open with it, generated from the build. Every input, the egress-policy default, and why ref is refused on contributor-controlled events: the action section.

Packages

Zuke ships as a JSR workspace of 58 packages: @zuke/core (the engine, the $ shell, and the tooling base classes), the @zuke/cli command, a generic @zuke/cmd fallback, plugins such as @zuke/ai, @zuke/console and @zuke/otel, and a typed wrapper per tool — @zuke/deno, @zuke/npm, @zuke/docker, @zuke/gh, @zuke/git, @zuke/kubectl, @zuke/terraform, @zuke/vite, @zuke/playwright, and more.

The full matrix with live JSR badges is in Packages. The complete typed surface of every package is in llms-full.txt (one file), summarised in llms.txt; for a single package run deno doc jsr:@zuke/<package>.

AI in your pipeline

Three ways a model joins the build, each a typed target with refactor-safe dependencies:

• Drive the coding CLIs. @zuke/claude, @zuke/codex and @zuke/gemini run Claude Code, OpenAI Codex and Gemini CLI non-interactively — a prompt, a model, a constrained tool set, JSON out — with the API key riding a parameter().secret() that Zuke masks in CI output. See Tools.
• AI code review that breaks the build. @zuke/ai reads the diff, returns a structured assessment (score, severity, findings), posts it to the pull request, and fails the run when the risk crosses your threshold. See AI code review.
• Self-healing targets. Attach .recoverWith(aiFixer(…)) to any target: on failure it diagnoses from the error and the diff and posts a committable suggestion — or, opted in, applies the fix, commits, and re-runs the real command to verify. agentFixer hands the failure to a coding agent instead. A shared budget(…) caps spend by token count. See Self-healing builds.

test = target()
  .executes(() => DenoTasks.test((s) => s.allowAll()))
  // On failure: diagnose, post a committable suggestion, optionally heal.
  .recoverWith(aiFixer((f) => f.provider("openai").apiKey(this.key)));

Agent skills

Two skills — zuke-setup and zuke-write-build — teach an AI coding assistant to scaffold Zuke and write a zuke.ts using the typed wrappers instead of guessing the API. Authored once as portable Agent Skills under skills/, and installable into every harness:

/plugin marketplace add zuke-build/zuke && /plugin install zuke@zuke   # Claude Code
codex plugin marketplace add zuke-build/zuke && codex plugin add zuke@zuke
gemini extensions install https://github.com/zuke-build/zuke

Per-harness details: Agent skills.

Documentation

Start here, then browse the full index in docs/:

• Getting started — install, scaffold, the launcher, zuke import, and a first build.
• Core concepts — the build/target/graph model and execution semantics.
• Authoring API — target(), Build, run(), code-first CI generation (cicd()), and gotchas.
• Parameters and Secrets — typed build inputs from flags and env vars, and secret values with guaranteed redaction.
• Shell wrapper ($) — ergonomic, injection-safe process execution.
• Packages and Tools — the package matrix, and every wrapper's tasks.
• Using Zuke in a Node/npm project — drive a Node build with Deno.
• MCP server and Agent skills — the build as typed tools for an agent, and the skills that teach one to write it.
• Caching, Service targets, Durable run state, Cross-run locks, Orchestration: waits — the layer for real deployments.
• CLI reference, Programmatic API, Versioning & compatibility, How Zuke compares.

Development

deno task test        # run the suite
deno task cov         # run with coverage + enforce the 95% gate
deno task check       # type-check
deno task fmt         # format (fmt:check to verify only)
deno task lint        # lint
deno task spell       # spell-check (cspell)
deno task ci          # the full gate — deno run -A --frozen zuke.ts ci

deno task ci is ./zuke ci, the same gate the ci job in .github/workflows/ci.yml runs on every push and pull request — see AGENTS.md for the full check list.

Contributing

Contributions are welcome! Start with CONTRIBUTING.md for the full workflow, and please be mindful of our Code of Conduct. AGENTS.md holds the coding standards (strict typing, no any/as, 95%+ coverage, hermetic tests); CLAUDE.md is a one-line pointer to it. Run deno task ci before opening a PR, add tests in the same change as the code they cover, and update docs when behaviour changes.

Security

As a build tool that runs in other people's pipelines, Zuke treats supply-chain integrity as a first-class concern: zero runtime dependencies, injection-free Deno.Command execution, OIDC trusted publishing with provenance, least-privilege and SHA-pinned CI, a frozen lockfile, and continuous scanning (zizmor, actionlint, gitleaks, CodeQL, and OpenSSF Scorecard) driven by a typed Zuke target through @zuke/security. See SECURITY.md for the full posture and how to report a vulnerability.

License

MIT — see LICENSE.

Acknowledgements

Zuke stands on the shoulders of giants:

• NUKE and its creator Matthias Koch — the code-first, strongly-typed build model that inspired Zuke. If you build for .NET, use NUKE; Zuke is an homage to its ideas in the Deno/TypeScript world.
• Spectre.Console and its creator Patrik Svensson — the .NET console library whose markup, themes, and rich widgets (rules, panels, tables) inspired the output model of @zuke/console.
• Deno — the runtime and toolchain (test runner, formatter, linter, type-checker, coverage) that makes a zero-dependency, hermetic build tool possible.
• JSR — modern, TypeScript-native package distribution.
• Every author of the tools Zuke wraps — Docker, Kubernetes, Terraform, Vite, Playwright, and the rest of the matrix.

Community & contact

Questions, ideas, or just want to say hi? Open an issue, or reach out:

Swag, activity & contributors

Swag

Zuke has a swag shop! Grab some Zuke-branded apparel and accessories and wear the build:

👉 https://totollyshop.myspreadshop.net/

Activity

Star history

If Zuke is useful to you, consider starring the repo — it helps others find the project. ⭐

Contributors