zuke 1.0.0__tar.gz

zuke-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,89 @@
+name: Bug report
+description: Report something in zuke-python that isn't working as documented.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug! A minimal reproduction is the
+        single most useful thing you can give us.
+
+        Before you start, please
+        [search existing issues](https://github.com/zuke-build/zuke-python/issues?q=is%3Aissue)
+        to avoid duplicates. **Do not report security vulnerabilities here** —
+        follow the private process in
+        [SECURITY.md](https://github.com/zuke-build/zuke-python/blob/main/SECURITY.md).
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: This is a bug, not a security vulnerability or a usage question.
+          required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear and concise description of the bug.
+      placeholder: Running `zuke test` fails to resolve a dependency that is declared above its dependent.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What did you expect to happen instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: >
+        The smallest build file and commands that reproduce the problem. Paste a
+        self-contained `build.py` (or snippet) and the exact command you ran.
+        Code blocks here are automatically formatted, so no backticks are needed.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: package
+    attributes:
+      label: Affected versions
+      description: The zuke-python version and the Zuke engine version it ran on.
+      placeholder: "zuke-python 0.1.0, zuke engine 2.0.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: "Python 3.12.x"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 14, Ubuntu 24.04, Windows 11, …"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs or output
+      description: Any error output, stack traces, or `--list`/`graph` output. Automatically formatted as code.
+      render: shell
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else that helps us understand the problem.
+    validations:
+      required: false

zuke-1.0.0/.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,57 @@
+name: Chore or documentation
+description: Track documentation, refactoring, tests, or repository work.
+title: "chore: "
+labels: ["chore"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Every change in this repository starts with an issue — including docs,
+        refactors, tests, and build work. This is the template for the work that
+        is neither a new capability nor a bug.
+
+        Please
+        [search existing issues](https://github.com/zuke-build/zuke-python/issues?q=is%3Aissue)
+        first to avoid duplicates.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: This is not a new capability or a bug report — those have their own templates.
+          required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What needs doing?
+      description: The change itself, concretely.
+      placeholder: Document the resolution order the tool wrappers use when both a local binary and a project-local install are present.
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why now?
+      description: What is harder, riskier, or more confusing than it should be until this lands?
+    validations:
+      required: true
+  - type: input
+    id: scope
+    attributes:
+      label: Affected area(s)
+      description: The packages, directories, or files involved.
+      placeholder: "docs/, AGENTS.md, .github/"
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: How a reviewer confirms this is done.
+      placeholder: |
+        - The resolution order is described in docs/tooling.md.
+        - `uv run poe ci` passes.
+    validations:
+      required: true

zuke-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/zuke-build/zuke-python/security/advisories/new
+    about: Do not file security issues publicly. Use private vulnerability reporting — see SECURITY.md.
+  - name: The Zuke engine and its protocol
+    url: https://github.com/zuke-build/zuke
+    about: The engine this SDK talks to, its tool wrappers, and the worker protocol live there.
+  - name: Contributing guide
+    url: https://github.com/zuke-build/zuke-python/blob/main/CONTRIBUTING.md
+    about: How to set up, run the gate, and open a good pull request.

zuke-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature request
+description: Suggest a new capability, tool wrapper, or improvement.
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea! If you are planning a large change, opening this
+        issue first lets us agree on the direction before you invest the effort.
+
+        Please
+        [search existing issues](https://github.com/zuke-build/zuke-python/issues?q=is%3Aissue)
+        first to avoid duplicates.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What are you trying to do, and what makes it hard today? Focus on the "why".
+      placeholder: I want to wrap the `foo` CLI as a typed `FooTasks` object so my build doesn't fall back to raw shell.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: >
+        How would you like it to work? Sketches of the public surface are
+        welcome. A new tool wrapper belongs in the engine repository, since the
+        Python facades are generated from it.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you weighed, including running the command through `ctx.sh`.
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links to the tool's CLI docs, related issues, or anything else that helps.
+    validations:
+      required: false

zuke-1.0.0/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  # Keep the SHA-pinned GitHub Actions current. Dependabot reads the version
+  # comment next to each pinned SHA and opens PRs that bump both together, so
+  # pinning to a commit never means going stale on security fixes.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: "ci"
+  # The development tools in pyproject.toml and uv.lock. The package itself has
+  # no runtime dependencies.
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      dev-tools:
+        patterns: ["*"]
+    commit-message:
+      prefix: "chore"

zuke-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,45 @@
+<!--
+Thanks for contributing to zuke-python! A few things that make review fast:
+
+The PR title IS the release trigger. This repo squash-merges, and
+release-please parses only the squashed subject (your PR title). Title this PR
+as a Conventional Commit so the right version is cut:
+
+  feat: add the service builder             -> minor bump
+  fix: honour the worker's cwd in exec      -> patch bump
+  docs|chore|refactor|test: ...             -> no release
+-->
+
+## What & why
+
+<!-- What does this change do, and what problem does it solve? Explain the
+motivation, not just the mechanics. -->
+
+## Related issues
+
+<!-- Required: "Closes #123". Every change starts with an issue — file one from
+.github/ISSUE_TEMPLATE (feature request, bug report, or chore) before opening
+this PR. See AGENTS.md. -->
+
+## Checklist
+
+- [ ] This PR closes a tracking issue (`Closes #<n>` above).
+- [ ] The PR title is a
+      [Conventional Commit](https://www.conventionalcommits.org/)
+      (`type(scope): summary`).
+- [ ] `uv run poe ci` passes locally (format, lint, type-check, tests).
+- [ ] Tests were added or updated; coverage stays at 95%+ (lines and branches).
+- [ ] Docs updated in the same PR (`README.md`, docstrings) when behaviour
+      changed.
+- [ ] No `Any`, no `cast`, no `type: ignore` in `src/` (narrow with guards
+      instead).
+- [ ] No dead code: unreachable branches and can't-fire fallbacks are removed,
+      with types tightened so the impossible state is unrepresentable.
+- [ ] No duplicated logic: an existing helper is imported rather than retyped.
+- [ ] A protocol change was made in the engine repository first, and this PR
+      pins the engine version that carries it.
+- [ ] The code is written using AI assisted coding.
+
+<!-- Keep illustrative code in this description, not in commit message bodies:
+release-please's strict parser can drop a commit whose body contains code with
+parentheses, silently skipping it from the release. -->

zuke-1.0.0/.github/workflows/ai-review.yml

@@ -0,0 +1,79 @@
+name: AI Review
+"on":
+  pull_request: {}
+  issue_comment:
+    types:
+      - created
+permissions:
+  contents: read
+concurrency:
+  group: "ai-review-${{ github.event.pull_request.number || github.event.issue.number }}"
+  cancel-in-progress: true
+jobs:
+  review:
+    name: AI review
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    if: "${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}"
+    timeout-minutes: 15
+    steps:
+      - name: Harden and check out with Zuke
+        uses: zuke-build/zuke@b0832247daa16321be405a10b71c022317d2c5a4 # v1.0.8
+        with:
+          egress-policy: block
+          persist-credentials: "false"
+          allowed-endpoints: "deno.land:443 dl.deno.land:443 jsr.io:443 github.com:443 api.github.com:443 codeload.github.com:443 objects.githubusercontent.com:443 release-assets.githubusercontent.com:443 pypi.org:443 files.pythonhosted.org:443 api.openai.com:443"
+      - name: Install uv
+        shell: bash
+        run: pipx install uv
+      - name: Sync the locked environment
+        shell: bash
+        run: uv sync --locked
+      - name: AI review with Zuke
+        run: ./zuke review
+        env:
+          OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+  commandReview:
+    name: AI review on command
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    if: "${{ github.event_name == 'issue_comment' && github.event.issue.pull_request && github.event.comment.user.type != 'Bot' && (startsWith(github.event.comment.body, '@zuke-build review') || startsWith(github.event.comment.body, '@zuke-build accept')) }}"
+    timeout-minutes: 15
+    steps:
+      - name: Harden and check out with Zuke
+        uses: zuke-build/zuke@b0832247daa16321be405a10b71c022317d2c5a4 # v1.0.8
+        with:
+          egress-policy: block
+          persist-credentials: "false"
+          allowed-endpoints: "deno.land:443 dl.deno.land:443 jsr.io:443 github.com:443 api.github.com:443 codeload.github.com:443 objects.githubusercontent.com:443 release-assets.githubusercontent.com:443 pypi.org:443 files.pythonhosted.org:443 api.openai.com:443"
+      - name: Install uv
+        shell: bash
+        run: pipx install uv
+      - name: Sync the locked environment
+        shell: bash
+        run: uv sync --locked
+      - name: Check the commenter may start a review
+        id: callers
+        run: ./zuke review_preflight
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          ZUKE_REVIEW_PR: "${{ github.event.issue.number }}"
+          ZUKE_REVIEW_COMMENT: "${{ github.event.comment.id }}"
+          ZUKE_REVIEW_ACTOR: "${{ github.event.comment.user.login }}"
+          ZUKE_REVIEW_ROLE: write
+        continue-on-error: true
+      - name: AI review with Zuke
+        if: "steps.callers.outcome == 'success'"
+        run: ./zuke review
+        env:
+          OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          ZUKE_REVIEW_PR: "${{ github.event.issue.number }}"
+          ZUKE_REVIEW_COMMENT: "${{ github.event.comment.id }}"
+          ZUKE_REVIEW_ACTOR: "${{ github.event.comment.user.login }}"
+          ZUKE_REVIEW_ROLE: write

zuke-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+"on":
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+permissions:
+  contents: read
+concurrency:
+  group: "ci-${{ github.ref }}"
+  cancel-in-progress: true
+jobs:
+  ci:
+    name: "Gate (${{ matrix.os }})"
+    runs-on: "${{ matrix.os }}"
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+    steps:
+      - name: Harden and check out with Zuke
+        uses: zuke-build/zuke@b0832247daa16321be405a10b71c022317d2c5a4 # v1.0.8
+        with:
+          egress-policy: audit
+          persist-credentials: "false"
+      - name: Install uv
+        shell: bash
+        run: pipx install uv
+      - name: Sync the locked environment
+        shell: bash
+        run: uv sync --locked
+      - name: Run the gate with the bash launcher
+        if: "runner.os != 'Windows'"
+        run: ./zuke ci
+      - name: Run the gate with the PowerShell launcher
+        if: "runner.os == 'Windows'"
+        shell: pwsh
+        run: ./zuke.ps1 ci
+      - name: Check the generated workflow is current
+        if: "runner.os != 'Windows'"
+        run: ./zuke generate-ci --check

zuke-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+"on":
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+concurrency:
+  group: "release-${{ github.ref }}"
+  cancel-in-progress: false
+jobs:
+  release:
+    name: "Maintain the release PR, and publish a cut release"
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    timeout-minutes: 15
+    steps:
+      - name: Harden and check out with Zuke
+        uses: zuke-build/zuke@b0832247daa16321be405a10b71c022317d2c5a4 # v1.0.8
+        with:
+          egress-policy: audit
+          persist-credentials: "false"
+      - name: Maintain the release PR and cut the release
+        id: release
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
+        with:
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json
+      - name: Install uv
+        if: steps.release.outputs.release_created
+        shell: bash
+        run: pipx install uv
+      - name: Sync the locked environment
+        if: steps.release.outputs.release_created
+        shell: bash
+        run: uv sync --locked
+      - name: Publish to PyPI with Zuke
+        if: steps.release.outputs.release_created
+        run: ./zuke publish

zuke-1.0.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+/dist/
+/build/
+*.egg-info/
+
+# Tooling caches and reports
+.ruff_cache/
+.pytest_cache/
+.coverage
+/coverage.xml
+/htmlcov/
+
+# Generated Zuke artifacts, once the build is a Zuke build
+/.zuke/
+
+# Editor / OS noise
+.DS_Store
+*.swp
+
+# Env
+.env

zuke-1.0.0/.release-please-config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "simple",
+  "bump-minor-pre-major": false,
+  "packages": {
+    ".": {
+      "package-name": "zuke",
+      "changelog-path": "CHANGELOG.md",
+      "extra-files": ["src/zuke/__init__.py"]
+    }
+  }
+}

zuke-1.0.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}