diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml new file mode 100644 index 0000000..2a41f67 --- /dev/null +++ b/.github/workflows/claude-code-review.yml @@ -0,0 +1,175 @@ +# Automatic Claude review of pull requests, built around this repo's rules +# (AGENTS.md): the plugin list, provider pages, golden tests with dated quotes, +# fetching only through the environment, precision over recall, and nothing +# private in a public repo. It ends with a clear verdict. +# +# Runs once per PR: when it's opened (not as a draft), marked ready, or reopened. +# New pushes don't re-run it, to save Claude usage. For a fresh review after +# changes, a maintainer comments `@claude review` (claude.yml). +# +# Pull requests from forks: GitHub gives their runs no secrets, so this +# workflow only runs for branches in this repository. On a fork's PR a +# maintainer comments `@claude review` instead; claude.yml reviews it read-only +# and never runs the fork's code. This workflow never uses `pull_request_target`. +# +# Auth: CLAUDE_CODE_OAUTH_TOKEN, a Claude subscription token from +# `claude setup-token`. Until it's available the job skips with a notice. +# +# Note: a PR that edits this file can't run it. The action refuses to run a +# workflow that differs from the one on main, so changes here only take effect +# after they merge. +name: Claude Code Review + +on: + pull_request: + types: [opened, ready_for_review, reopened] + +# One review per PR at a time; a newer trigger cancels the run it supersedes. +concurrency: + group: claude-review-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + review: + # Drafts are work in progress; review them once they're marked ready. + # Only branches in this repository: a fork's run gets no secrets. + if: >- + github.event.pull_request.draft == false && + github.event.pull_request.head.repo.full_name == github.repository + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read + pull-requests: write # the review comment and inline comments + issues: write # PR comments go through the issues API + id-token: write # the action authenticates as the Claude GitHub App + env: + # Skip quietly instead of failing red until the secret is available. + HAS_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }} + steps: + - name: Skip (CLAUDE_CODE_OAUTH_TOKEN not set) + if: env.HAS_TOKEN != 'true' + run: echo "::notice::CLAUDE_CODE_OAUTH_TOKEN is not set; skipping Claude review." + + - uses: actions/checkout@v6 + if: env.HAS_TOKEN == 'true' + with: + fetch-depth: 1 + + # Go, so Claude can verify by running instead of only reading. + - uses: actions/setup-go@v7 + if: env.HAS_TOKEN == 'true' + with: + go-version-file: go.mod + cache-dependency-path: go.sum + + - uses: anthropics/claude-code-action@v1 + id: claude + if: env.HAS_TOKEN == 'true' + env: + # Any sub-agent Claude starts at the Opus tier also runs Opus 5.5. + ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-5-5 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + # The action creates the review comment itself and Claude fills it in, + # so a review can never end in silence. Sticky: one comment per PR. + track_progress: true + use_sticky_comment: true + # Public repo: the run summary is public, so don't print Claude's report there. + display_report: false + prompt: | + REPO: ${{ github.repository }} + PR NUMBER: ${{ github.event.pull_request.number }} + + Review this pull request against this repo's rules. Read AGENTS.md first: it + holds the rules for plugins, the public-repo rule, the commands and the layout. + CONTRIBUTING.md and .github/pull_request_template.md say the same for contributors. + + HOW TO RUN COMMANDS: one plain command per Bash call. Pipes (|), redirects + (>), `&&`, `;` and `$(...)` are blocked and will waste a turn. Read files + with the Read tool, and search with Grep/Glob, never with cat, grep or find. + + 1. THE CHANGE. Read the PR title and body with `gh pr view `, and + any issue it references with `gh issue view `. Read the diff with + `gh pr diff `, and changed files in full where the diff isn't + enough context. + 2. THE PLUGIN LIST (AGENTS.md Rule 1). Every plugin added, removed, or with a + changed id, provider, source, what it watches, format plugin or status has + its row added, removed or updated in docs/plugins.md, between the + `` and `` markers, as a plain + Markdown table with absolute links only. Compare the registered plugins with + the table yourself; a missing row is blocking. + 3. PROVIDER PAGE. Every new provider has providers/.md copied from + providers/_template.md, with a real **Why this source**: the link, the date + it was checked, why it's the best source, the alternatives not used, and a + short quote. A changed source updates that page. + 4. TESTS AND SOURCES. A golden test over a real saved copy of the source + (testdata/golden/.json); a row in testdata/README.md for each file + (URL, date fetched, license, quote of the part the plugin reads); one pinned + drop test (a realistic input that produces no event); every event carries + the source URL and a quote. A golden file edited without the PR explaining + why the new output is right is blocking. + 5. PLUGIN CODE. Fetch only through env.Get or kit/: no net/http outside the + fetch layer (fetch/, kit/, adapter/), no filesystem outside testdata/, no + database. Precision over recall: flag any path that could emit an event for + something that isn't a real change; a wrong event becomes a wrong pull + request in someone's repo. Don't change contract/fixtures/ here first (the + contract is owned upstream). + 6. NOTHING PRIVATE (AGENTS.md Rule 2). This repo is public. Flag credentials, + tokens, keys, internal hostnames or service names, links to private repos, + dashboards or tickets, names or emails of customers or users, anything + about sales, and links to AI chat or agent sessions, in code, tests, docs, + commit messages and the PR description. + 7. CORRECTNESS. Real problems only: code that won't build or run, wrong + results, broken edge cases. No style nitpicks. Put each specific problem as + an inline comment on its line. + 8. VERIFY BY RUNNING. Run `go build ./...`, `go vet ./...`, `gofmt -l .` + (must print nothing), `go test -race ./...` and + `python3 scripts/leak_guard.py --all`. Report what you ran and what + happened; don't claim anything you didn't check. + + Your final comment is what the author reads, and it is public. Start with ONE + verdict line: "✅ Ready to merge", "⚠️ Merge after fixes" or "❌ Not ready", + with a one-sentence reason. Then, concisely: + - **Rules**: a table of rule | status | evidence (plugin list, provider page, + golden test and quote, drop test, fetch only via env, nothing private) + - **Bugs**: blocking problems, or "none found" + - **Verified**: the commands you ran and their results + - **Non-blocking**: optional small suggestions, clearly marked as such + Be kind and specific: many authors here are outside contributors. + Never include a Claude session ID or claude.ai link. + # Read-only on GitHub, plus the Go toolchain and the leak guard to verify. + # No `gh pr comment` and no `gh api`: the action posts the review comment + # itself. Default permission mode: anything not listed here is denied. + claude_args: >- + --model claude-opus-5-5 + --permission-mode default + --allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*),Bash(go build:*),Bash(go vet:*),Bash(go test:*),Bash(gofmt -l:*),Bash(python3 scripts/leak_guard.py:*)" + --disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*)" + + # Diagnostics only: print the number of blocked tool calls and which tools, + # so a disappointing review can be fixed instead of guessed at. Public repo: + # it doesn't print Claude's message or the tool inputs. + - name: Log blocked tool calls + if: always() && env.HAS_TOKEN == 'true' && steps.claude.outputs.execution_file != '' + continue-on-error: true + env: + EXECUTION_FILE: ${{ steps.claude.outputs.execution_file }} + run: | + python3 - <<'PY' + import json, os + + try: + data = json.load(open(os.environ["EXECUTION_FILE"])) + except Exception as e: + print(f"No execution output to read: {e}") + raise SystemExit(0) + + messages = data if isinstance(data, list) else [data] + result = next((m for m in reversed(messages) if m.get("type") == "result"), {}) + denials = result.get("permission_denials") or [] + + print(f"=== Blocked tool calls: {len(denials)} ===") + for d in denials: + print(f"BLOCKED {d.get('tool_name')}") + PY diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml new file mode 100644 index 0000000..4fc0a79 --- /dev/null +++ b/.github/workflows/claude.yml @@ -0,0 +1,71 @@ +# Claude on demand: a maintainer mentions @claude in a PR comment, a review or a +# review comment, and Claude replies in the same thread. `@claude review` on a +# PR gets a full review against this repo's rules, including PRs from forks. +# +# This repo is public, so this workflow is locked down: +# - Only maintainers trigger it: the commenter's author_association must be +# OWNER, MEMBER or COLLABORATOR, or no runner starts. The action then checks +# write access itself. Bots can't trigger it. +# - Read and comment only. Claude can read the repo and the PR, and reply; it +# can't edit files, commit, push, run commands or fetch web pages +# (`--permission-mode default`, so anything not allowed below is denied). +# - On a fork's PR the action checks out the fork's code to read, but restores +# Claude's config (CLAUDE.md, AGENTS.md, .claude/) from main, and Claude runs +# none of the fork's code. Never uses `pull_request_target`. +# +# Auth: CLAUDE_CODE_OAUTH_TOKEN, same as claude-code-review.yml. +name: Claude + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + pull_request_review: + types: [submitted] + +jobs: + claude: + # Only a maintainer's comment that mentions @claude starts a runner. + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && + contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && + contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && + contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association)) + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read + pull-requests: write # replies and inline comments + issues: write # PR comments go through the issues API + id-token: write # the action authenticates as the Claude GitHub App + actions: read # lets Claude read CI results on PRs + env: + HAS_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }} + steps: + - name: Skip (CLAUDE_CODE_OAUTH_TOKEN not set) + if: env.HAS_TOKEN != 'true' + run: echo "::notice::CLAUDE_CODE_OAUTH_TOKEN is not set; skipping Claude." + + # The base branch. The action itself checks out the PR's code to read. + - uses: actions/checkout@v6 + if: env.HAS_TOKEN == 'true' + with: + fetch-depth: 1 + + - uses: anthropics/claude-code-action@v1 + if: env.HAS_TOKEN == 'true' + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + # Public repo: the run summary is public, so don't print Claude's report there. + display_report: false + # Read-only plus commenting. No Bash beyond reading the PR and issues, + # no edits, no commits or pushes, no web. + claude_args: >- + --model claude-opus-5-5 + --permission-mode default + --allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*)" + --disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*),Bash(git add:*),Bash(git rm:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files" + --append-system-prompt "This is patch-it-plugins, a public repo of source plugins. Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check it against AGENTS.md: (1) every new, changed or removed plugin has its row added, updated or removed in docs/plugins.md between the plugins:start and plugins:end markers, absolute links only; (2) every new provider has providers/.md from providers/_template.md with a real 'Why this source' (link, date checked, why it's best, alternatives, quote); (3) a golden test over a real saved source, a testdata/README.md row (URL, date fetched, license, quote), one pinned drop test, every event carries its source URL and a quote, and golden edits are explained; (4) fetch only through env.Get or kit/, no net/http outside fetch/, kit/ and adapter/, no filesystem outside testdata/; (5) precision over recall: flag anything that could emit an event for a non-change; (6) nothing private: no credentials, internal hostnames or service names, links to private repos or tickets, customer names, or links to AI sessions. You can't run the tests; say that CI_go covers them. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then a table of rule | status | evidence, blocking bugs, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc00fcb..74771ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,6 +28,7 @@ That adds `Signed-off-by: Your Name `, matching the commit's au - Commit subjects: short, lowercase, imperative (`add the foo plugin`, `fix stripe hint parsing`). - Run the tests before you push (see [README](README.md#run-the-tests)). - A maintainer listed in `.github/CODEOWNERS` reviews every PR. +- **Reviews:** Claude also reviews each PR against the rules above, once, when it's opened or marked ready. PRs from forks get no secrets, so for those a maintainer comments `@claude review` and Claude reviews it read-only (it never runs a fork's code). Only maintainers can call `@claude`. Claude's review helps; a maintainer still decides. ## CI @@ -36,6 +37,7 @@ That adds `Signed-off-by: Your Name `, matching the commit's au | `CI_go` | `go mod tidy`, build, vet, gofmt, `go test -race`; plugins import only this module, the standard library and approved dependencies; `net/http` only in the fetch layer | | `CI_dco` | Every commit in the PR is signed off by its author | | `CI_leak_guard` | gitleaks over the PR's commits, and a check for known internal names (stored as hashes only). Also runs weekly over the whole repo | +| `Claude Code Review` | Claude reviews the PR against the rules above, once (PRs from this repo's branches; forks: a maintainer comments `@claude review`). Advisory, not a required check | ## License