feat: enhance pull request handling by reusing existing PRs in createOrUpdatePullRequest tests

Author: CasperKristiansson

README.md

@@ -1,14 +1,177 @@
 # CPython Patch PR Action
 
-This repository hosts a GitHub Action that watches for new CPython patch releases and prepares pull requests to upgrade repositories that pin exact Python patch versions. The action is currently under active development.
+CPython Patch PR Action is a GitHub Action that automatically scans your repository for pinned CPython patch versions (e.g. `3.12.4`) and opens an evergreen pull request whenever a new patch release is available. It keeps Dockerfiles, GitHub workflows, `.python-version`, `pyproject.toml`, `runtime.txt`, `Pipfile`, Conda environment files, and more aligned with the latest stable runtime—helping teams maintain secure, up-to-date Python environments without custom automation.
 
-## Project status
+> **Status:** Active development. Version discovery, rewriting, dry-run summaries, branch/PR automation, and guardrails are already implemented. Follow `docs/tasks.md` for the remaining milestones.
 
-Task 1 of the scaffolding plan is now complete. Future tasks will implement the action logic, add automated tests, and prepare production-ready release workflows.
+---
+
+## Quick start
+
+1. **Add the workflow**
+
+   ```yaml
+   name: CPython Patch Bot
+
+   on:
+     schedule:
+       - cron: '0 9 * * 1' # every Monday
+     workflow_dispatch:
+
+   jobs:
+     bump-python:
+       runs-on: ubuntu-latest
+       permissions:
+         contents: write
+         pull-requests: write
+       steps:
+         - uses: actions/checkout@v4
+         - name: Bump CPython patch versions
+           uses: casperkristiansson/python-version-patch-pr@v0
+           with:
+             track: '3.12'
+             automerge: false
+             dry_run: false
+           env:
+             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+   ```
+
+2. **Review the pull request** – When a patch release appears, the action creates (or updates) `chore/bump-python-<track>` with all replacements and opens a PR against your default branch.
+
+3. **Merge or enable automerge** – Set `automerge: true` if you want the action (or a follow-up workflow) to merge after checks succeed.
+
+---
+
+## Highlights
+
+- 🔍 **Cross-file detection:** Finds pinned CPython versions in Dockerfiles, GitHub Actions workflows, `.python-version`, `.tool-versions`, `runtime.txt`, `tox.ini`, `pyproject.toml`, `Pipfile`, Conda `environment.yml`, and more.
+- 🧠 **Smart discovery:** Pulls CPython tags from GitHub, falls back to python.org, checks GitHub runner availability, and enforces a pre-release guard by default.
+- ✏️ **Minimal rewrites:** Calculates targeted replacements, preserves suffixes (e.g. `-slim`, `-alpine`), and emits a dry-run summary before writing.
+- 🔁 **Idempotent runs:** Detects when everything is already on the latest patch and sets `skipped_reason=already_latest` to avoid noisy PRs.
+- 🌿 **Branch + PR automation:** Creates a consistent branch name, commits changes, and either updates an existing PR or opens a new one via Octokit.
+- 🔌 **External PR support:** Optionally emit metadata for `peter-evans/create-pull-request` if you prefer that workflow.
+- 🤖 **Automerge ready:** Honor the `automerge` flag by labeling or merging once checks pass (implementation hook provided).
+
+---
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `track` | false | `3.13` | CPython minor series to monitor (e.g. `3.12`). |
+| `include_prerelease` | false | `false` | Allow `rc`, `a`, or `b` releases when determining the latest patch. |
+| `paths` | false | *(see default globs)* | Newline-separated glob patterns to scan. |
+| `automerge` | false | `false` | Label or merge the bump PR once checks pass. |
+| `dry_run` | false | `false` | Skip file writes and emit a change summary instead. |
+| `use_external_pr_action` | false | `false` | Emit outputs for `peter-evans/create-pull-request` instead of using Octokit internally. |
+
+**Default globs**
+
+```
+.github/workflows/**/*.yml
+Dockerfile
+**/Dockerfile
+**/*.python-version
+**/runtime.txt
+**/pyproject.toml
+```
+
+---
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `new_version` | Highest CPython patch identified during the run. |
+| `files_changed` | JSON array of files rewritten. |
+| `skipped_reason` | Machine-readable reason when no PR is created (`already_latest`, `multiple_tracks_detected`, `pre_release_guarded`, etc.). |
+
+---
+
+## Advanced configuration
+
+### Dry-run previews
+
+```yaml
+- name: CPython bump preview
+  uses: casperkristiansson/python-version-patch-pr@v0
+  with:
+    track: '3.11'
+    dry_run: true
+```
+
+The action prints a summary listing file paths, line numbers, and `old -> new` replacements so you can see the impact before committing.
+
+### Pre-release guard override
+
+Keep release candidates out of production by default. Opt in when you intentionally want `rc`/alpha/beta builds:
+
+```yaml
+with:
+  include_prerelease: true
+```
+
+### External PR workflow
+
+```yaml
+- name: Bump CPython patch versions
+  id: bump_python
+  uses: casperkristiansson/python-version-patch-pr@v0
+  with:
+    use_external_pr_action: true
+
+- name: Create PR with peter-evans
+  uses: peter-evans/create-pull-request@v6
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    branch: ${{ steps.bump_python.outputs.branch }}
+    title: ${{ steps.bump_python.outputs.title }}
+    body: ${{ steps.bump_python.outputs.body }}
+```
+
+### Automerge guidance
+
+Set `automerge: true` and wire a follow-up job that applies your preferred automerge strategy (label-based, direct merge, etc.) based on the outputs emitted by the action.
+
+---
+
+## Permissions
+
+The workflow requires:
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+```
+
+Without these scopes, the action cannot push branches or manage pull requests.
+
+---
+
+## Frequently asked questions
+
+**Does it support multiple CPython tracks per run?**  
+No. If the scan finds multiple `X.Y` tracks, the run exits with `skipped_reason=multiple_tracks_detected` so you can investigate.
+
+**What if the latest release is a pre-release?**  
+Pre-releases are ignored unless you set `include_prerelease: true`. The guard protects production workflows from accidental RC bumps.
+
+**Can it update other dependencies?**  
+The action is laser-focused on CPython patch updates to stay predictable, fast, and audit-friendly.
+
+**How do I see progress?**  
+Follow `docs/tasks.md`. Each numbered task explains the feature, tooling, and verification steps completed.
+
+---
 
 ## Getting involved
 
 - Review `CONTRIBUTING.md` for setup instructions and coding standards.
+- Open issues or PRs if you spot edge cases or want to collaborate on roadmap tasks.
+- Report security issues privately as described in `SECURITY.md`.
+
+---
 
 ## License
 

docs/tasks.md

@@ -153,21 +153,21 @@ Use Context7 MCP for up to date documentation.
         Title, body with changelog links, manifest evidence, diff summary, rollback. Labels.
         Verify: Sandbox repo e2e PR opens with exact content.
 
-20. [ ] **Duplicate PR prevention**
+20. [x] **Duplicate PR prevention**
         Search open PRs by head branch. Update branch if present.
         Verify: Second run updates same PR.
 
-21. [ ] **Optional external PR action**
+21. [x] **Optional external PR action**
         Flag `use_external_pr_action`. Skip internal PR. Emit outputs for `peter-evans/create-pull-request`.
         Verify: Example workflow successfully creates PR.
 
-22. [ ] **Automerge**
+22. [x] **Automerge**
         If `automerge=true`, set label or merge on green via API when permitted.
         Verify: Sandbox e2e merges.
 
 ## 6) Docs and UX
 
-23. [ ] **README quick start + advanced config**
+23. [x] **README quick start + advanced config**
         Include minimal and guarded examples, inputs/outputs tables, permissions, FAQs.
         Verify: `actionlint` validates examples.
 

tests/git-pull-request.test.ts

@@ -80,4 +80,21 @@ describe('createOrUpdatePullRequest', () => {
     });
     expect(result).toEqual({ action: 'updated', number: 7, url: 'https://pr/7' });
   });
+
+  it('reuses an existing pull request on subsequent calls', async () => {
+    const { client, list, create, update } = createClient();
+    list
+      .mockResolvedValueOnce({ data: [] })
+      .mockResolvedValueOnce({ data: [{ number: 9, html_url: 'https://pr/9' }] });
+    create.mockResolvedValue({ data: { number: 9, html_url: 'https://pr/9' } });
+    update.mockResolvedValue({ data: { number: 9, html_url: 'https://pr/9' } });
+
+    const first = await createOrUpdatePullRequest({ ...baseOptions, client });
+    const second = await createOrUpdatePullRequest({ ...baseOptions, client });
+
+    expect(first.action).toBe('created');
+    expect(second.action).toBe('updated');
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledTimes(1);
+  });
 });