diff --git a/.github/workflows/contract.yml b/.github/workflows/contract.yml new file mode 100644 index 0000000..e6d3428 --- /dev/null +++ b/.github/workflows/contract.yml @@ -0,0 +1,65 @@ +# SPDX-FileCopyrightText: 2026 Igor Santos +# SPDX-License-Identifier: Apache-2.0 +# +# The contract with the playbook binary. intents.json lists the intents the +# plugin relies on. This job downloads the latest released playbook binary, +# checks its SHA256SUMS entry and compares `playbook tools map --json` with the +# list. A listed intent the binary lacks is a warning, and a failure only when +# intents.json marks it required. A daily run catches a binary release that +# drops an intent. + +name: contract + +on: + pull_request: + merge_group: + workflow_dispatch: + schedule: + - cron: "41 6 * * *" + +permissions: + contents: read + +concurrency: + group: contract-${{ github.ref }} + cancel-in-progress: true + +jobs: + contract: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + with: + egress-policy: block + allowed-endpoints: > + api.github.com:443 + github.com:443 + objects.githubusercontent.com:443 + release-assets.githubusercontent.com:443 + + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Lint the script + run: shellcheck --severity=warning scripts/*.sh + + - name: Download the latest playbook release + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + tag="$(gh release list --repo pragmatic-engineer/playbook --limit 100 --json tagName,isDraft,isPrerelease \ + --jq '[.[] | select(.isDraft == false and .isPrerelease == false) | .tagName | select(test("^v[0-9]+\\.[0-9]+\\.[0-9]+$"))] | first // empty')" + [ -n "$tag" ] || { echo "::error::no playbook release found"; exit 1; } + asset="playbook-${tag#v}-x86_64-unknown-linux-musl" + mkdir -p "$RUNNER_TEMP/playbook" + gh release download "$tag" --repo pragmatic-engineer/playbook \ + --pattern "$asset" --pattern SHA256SUMS --dir "$RUNNER_TEMP/playbook" + (cd "$RUNNER_TEMP/playbook" && grep " ${asset}\$" SHA256SUMS | sha256sum -c -) + chmod +x "$RUNNER_TEMP/playbook/$asset" + echo "PLAYBOOK_BIN=$RUNNER_TEMP/playbook/$asset" >> "$GITHUB_ENV" + + - name: Compare intents.json with the tool map + run: scripts/check-intents.sh "$PLAYBOOK_BIN" diff --git a/README.md b/README.md index ae292b7..758a3e1 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,10 @@ shell/check-marketplace.sh `shell/check-marketplace.sh` keeps installs keyless: a plugin source is either a path in this repository, or an https url or archive, and an archive carries a sha256. +## The binary contract + +`intents.json` lists the tool intents the plugin relies on, named like the entries of `playbook tools map`. The `contract` workflow downloads the latest released playbook binary and compares its tool map with the list. A missing intent is a warning, and a failure only for an entry marked `required`. Run it by hand with `scripts/check-intents.sh [path-to-playbook]`. + ## The hooks plugin pin `playbook-hooks` is versioned with the playbook binary. Its entry points at the release archive `playbook-hooks-plugin-.zip` in `pragmatic-engineer/playbook` and pins its sha256. The `pin-hooks` workflow runs daily at 06:37 UTC and can be started by hand. If a newer playbook release carries the archive, it runs `shell/bump-marketplace.sh`, which downloads the archive, verifies its build provenance attestation and writes the URL and the sha256 of those exact bytes. The workflow commits the change to a `bump/hooks-v` branch through the GitHub API, opens a pull request, approves the held checks run, waits for it to pass and squash merges. It uses only the built-in `GITHUB_TOKEN`. Don't edit the pin by hand. diff --git a/intents.json b/intents.json new file mode 100644 index 0000000..e5f4dc7 --- /dev/null +++ b/intents.json @@ -0,0 +1,194 @@ +[ + { + "intent": "add-glossary-term", + "required": false + }, + { + "intent": "atlassian-check", + "required": false + }, + { + "intent": "checkpoint", + "required": false + }, + { + "intent": "commit-prepare", + "required": false + }, + { + "intent": "commit-run", + "required": false + }, + { + "intent": "config-get", + "required": false + }, + { + "intent": "effort-choose", + "required": false + }, + { + "intent": "effort-resolve", + "required": false + }, + { + "intent": "gate-check", + "required": false + }, + { + "intent": "gate-record", + "required": false + }, + { + "intent": "gate-snapshot", + "required": false + }, + { + "intent": "handoff-check", + "required": false + }, + { + "intent": "handoff-facts", + "required": false + }, + { + "intent": "handoff-save", + "required": false + }, + { + "intent": "handoff-show", + "required": false + }, + { + "intent": "handoff-template", + "required": false + }, + { + "intent": "implement-dir", + "required": false + }, + { + "intent": "learn-collect", + "required": false + }, + { + "intent": "learn-preflight", + "required": false + }, + { + "intent": "list-plans", + "required": false + }, + { + "intent": "memory-context", + "required": false + }, + { + "intent": "memory-rebuild", + "required": false + }, + { + "intent": "mode-status", + "required": false + }, + { + "intent": "next-adr-number", + "required": false + }, + { + "intent": "plans-dir", + "required": false + }, + { + "intent": "pr-ci-wait", + "required": false + }, + { + "intent": "pr-comments", + "required": false + }, + { + "intent": "pr-create", + "required": false + }, + { + "intent": "pr-land-wait", + "required": false + }, + { + "intent": "pr-merge", + "required": false + }, + { + "intent": "pr-prepare", + "required": false + }, + { + "intent": "pr-reply", + "required": false + }, + { + "intent": "pr-review-triage", + "required": false + }, + { + "intent": "pr-rules", + "required": false + }, + { + "intent": "pr-stack", + "required": false + }, + { + "intent": "review-checks", + "required": false + }, + { + "intent": "review-prepare", + "required": false + }, + { + "intent": "review-size", + "required": false + }, + { + "intent": "review-triage-merge", + "required": false + }, + { + "intent": "review-worktree-setup", + "required": false + }, + { + "intent": "review-worktree-teardown", + "required": false + }, + { + "intent": "route-model", + "required": false + }, + { + "intent": "run-mode", + "required": false + }, + { + "intent": "segment-branch", + "required": false + }, + { + "intent": "segment-resplit", + "required": false + }, + { + "intent": "segment-size", + "required": false + }, + { + "intent": "work-unit-briefs", + "required": false + }, + { + "intent": "worktrees-dir", + "required": false + } +] diff --git a/scripts/check-intents.sh b/scripts/check-intents.sh new file mode 100755 index 0000000..fbac478 --- /dev/null +++ b/scripts/check-intents.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2026 Igor Santos +# SPDX-License-Identifier: Apache-2.0 +# +# check-intents.sh: the contract between this repo and the playbook binary. +# +# intents.json lists the intents the skills, commands and agents rely on, each +# named like a tool map entry (for example `pr-reply`). The binary prints its +# own list with `playbook tools map --json`. This script: +# 1. fails when intents.json is not valid: sorted, unique ids in kebab case +# with a boolean `required` field; +# 2. when a playbook binary is given, warns about each listed intent the +# binary does not offer, and fails only for an intent marked required. +# +# Usage: check-intents.sh [path-to-playbook-binary] +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +FILE="$ROOT/intents.json" +fail=0 + +jq -e 'type == "array" and length > 0' "$FILE" >/dev/null || { echo "FAIL intents.json must be a non-empty array"; exit 1; } +if ! jq -e 'all(.[]; (.intent | type == "string" and test("^[a-z][a-z0-9]*(-[a-z0-9]+)*$")) and (.required | type == "boolean"))' "$FILE" >/dev/null; then + echo "FAIL every entry needs a kebab-case intent and a boolean required"; exit 1 +fi +if [ "$(jq -r '[.[].intent] | . == (sort | unique)' "$FILE")" != "true" ]; then + echo "FAIL intents must be sorted and unique"; exit 1 +fi +echo "PASS intents.json lists $(jq length "$FILE") intents" + +bin="${1:-}" +if [ -z "$bin" ]; then + echo "SKIP no playbook binary given, offered intents not compared" + exit 0 +fi +if ! map="$("$bin" tools map --json 2>/dev/null)" || ! printf '%s' "$map" | jq -e 'type == "array"' >/dev/null 2>&1; then + echo "WARN $("$bin" --version 2>&1 | head -1) has no tools map yet, offered intents not compared" + exit 0 +fi +offered="$(printf '%s' "$map" | jq -r '.[].intent' | sort -u)" +while IFS=$'\t' read -r intent required; do + if printf '%s\n' "$offered" | grep -qx "$intent"; then + continue + fi + if [ "$required" = "true" ]; then + echo "FAIL required intent $intent is not in the tool map"; fail=1 + else + echo "WARN intent $intent is not in the tool map" + fi +done < <(jq -r '.[] | [.intent, (.required | tostring)] | @tsv' "$FILE") +exit "$fail"