prwatcher 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # prwatcher
 
-CLI tool that watches GitHub PRs and sends Slack notifications when CI passes, fails, or the PR is ready to merge.
+CLI tool that watches GitHub PRs and sends Slack notifications when CI passes, fails, or the PR is ready to merge. Optionally auto-merges when all checks pass.
 
 **Zero setup for developers** — just run one command. No Slack app creation, no servers, no ngrok.
 
@@ -29,17 +29,39 @@ Or use directly with npx:
 npx prwatcher https://github.com/owner/repo/pull/123
 ```
 
+### GitHub Token Setup
+
+On first run you'll be prompted for a GitHub personal access token. Here's what permissions it needs depending on how you use the tool:
+
+#### Watching only (no auto-merge)
+
+**Classic token** — check `repo` scope
+
+**Fine-grained token** — enable:
+- `Metadata` → Read-only (required)
+- `Pull requests` → Read-only
+
+#### Watching + Auto-merge (`--auto-merge`)
+
+**Classic token** — check `repo` scope
+
+**Fine-grained token** — enable:
+- `Metadata` → Read-only (required)
+- `Pull requests` → Read and write
+- `Contents` → Read and write ← required for merging
+
+> Your token is saved to `~/.watch-pr` on your machine with owner-only permissions (0600). It is never sent anywhere except the GitHub API.
+
 ### Usage
 
 ```bash
 prwatcher https://github.com/owner/repo/pull/123
 ```
 
-On first run, you'll be prompted for:
-1. **GitHub token** — [create one here](https://github.com/settings/tokens) with `repo` scope
-2. **Slack webhook URL** — your team's [Incoming Webhook](https://api.slack.com/messaging/webhooks)
+On first run, you'll also be prompted for:
+- **Slack webhook URL** — your team's [Incoming Webhook](https://api.slack.com/messaging/webhooks)
 
-These are saved to `~/.prwatcher` so you only enter them once.
+Both are saved to `~/.watch-pr` so you only enter them once.
 
 ### Options
 
@@ -48,6 +70,7 @@ prwatcher <pr-url> [options]
 
 Options:
   --interval <minutes>   Polling interval in minutes (default: 1)
+  --auto-merge           Automatically merge PR once all required checks pass
   --reset-config         Re-enter GitHub token and Slack webhook URL
   -V, --version          Output version number
   -h, --help             Display help
@@ -59,6 +82,9 @@ Options:
 # Watch a PR with default 1-minute polling
 prwatcher https://github.com/org/repo/pull/42
 
+# Watch and auto-merge when ready
+prwatcher https://github.com/org/repo/pull/42 --auto-merge
+
 # Poll every 30 seconds
 prwatcher https://github.com/org/repo/pull/42 --interval 0.5
 
@@ -78,8 +104,10 @@ You'll get Slack messages when:
 | Required CI checks fail | ⚠️ CI checks failed (lists which ones) |
 | PR needs rebase | 🔄 PR needs rebase |
 | PR is ready to merge | ✅ PR is ready to merge! |
+| PR is auto-merged | 🎉 PR was auto-merged! |
 | PR is merged | 🎉 PR was merged! |
 | PR is closed | ❌ PR was closed without merging |
+| Auto-merge failed | ⚠️ Auto-merge failed (with reason) |
 
 Notifications only fire on **state changes** — no spam.
 
@@ -113,6 +141,7 @@ Detect state change (CI failed, ready, merged, etc.)
      ↓
 POST to Slack webhook
      ↓
+--auto-merge? → merge via GitHub API → exit
 PR merged/closed? → exit
 ```
 

package/bin/watch-pr.js

@@ -6,9 +6,10 @@ const { run } = require('../src/cli');
 program
   .name('prwatcher')
   .description('Watch a GitHub PR and get Slack notifications on state changes')
-  .version('2.0.0')
+  .version('2.1.0')
   .argument('<pr-url>', 'GitHub PR URL (e.g., https://github.com/owner/repo/pull/123)')
   .option('--interval <minutes>', 'polling interval in minutes', '1')
+  .option('--auto-merge', 'automatically merge PR once all required checks pass')
   .option('--reset-config', 're-enter GitHub token and Slack webhook URL')
   .action((prUrl, options) => {
     run(prUrl, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prwatcher",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "CLI tool that watches GitHub PRs and sends Slack notifications when CI passes, fails, or PR is ready to merge",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -1,6 +1,6 @@
 const { parsePRUrl, buildPRKey } = require('./utils');
 const { ensureConfig } = require('./config');
-const { createClient, fetchRequiredChecks, fetchPRState } = require('./github');
+const { createClient, fetchRequiredChecks, fetchPRState, mergePR } = require('./github');
 const { sendNotification, formatMerged, formatClosed, formatCIFailed, formatRebaseNeeded, formatReady } = require('./slack');
 
 async function run(prUrl, options = {}) {
@@ -70,6 +70,9 @@ async function run(prUrl, options = {}) {
   const intervalMs = intervalMinutes * 60 * 1000;
 
   console.log(`   Polling every ${intervalMinutes >= 1 ? `${intervalMinutes} minute(s)` : `${intervalMinutes * 60} seconds`}`);
+  if (options.autoMerge) {
+    console.log('   ⚠  Auto-merge is ON — PR will be merged automatically when ready');
+  }
   console.log('   Press Ctrl+C to stop\n');
 
   // 6. Poll function
@@ -127,6 +130,24 @@ async function run(prUrl, options = {}) {
           console.log(`   ✅ ${timestamp} — Ready to merge!`);
           await sendNotification(config.slackWebhookUrl, formatReady(state.htmlUrl, state.title));
           lastState = 'ready';
+
+          if (options.autoMerge) {
+            try {
+              console.log(`   🔀 ${timestamp} — Auto-merging...`);
+              await mergePR(octokit, { owner, repo, prNumber });
+              console.log(`   🎉 ${timestamp} — Auto-merged!`);
+              await sendNotification(config.slackWebhookUrl, `🎉 *PR was auto-merged!*\n<${state.htmlUrl}|${state.title}>`);
+              cleanup();
+              process.exit(0);
+            } catch (mergeError) {
+              const mergeMsg = mergeError.response?.data?.message || mergeError.message;
+              const hint = mergeError.status === 403
+                ? ' (GitHub token needs "repo" scope or "Pull requests: write" permission)'
+                : '';
+              console.error(`   ⚠  ${timestamp} — Auto-merge failed: ${mergeMsg}${hint}`);
+              await sendNotification(config.slackWebhookUrl, `⚠️ *Auto-merge failed*\n<${state.htmlUrl}|${state.title}>\nReason: ${mergeMsg}${hint}`);
+            }
+          }
         } else {
           console.log(`   ✅ ${timestamp} — Still ready (already notified)`);
         }

package/src/github.js

@@ -115,8 +115,23 @@ async function fetchPRState(octokit, { owner, repo, prNumber, requiredCheckNames
   };
 }
 
+/**
+ * Merge a PR via GitHub API.
+ * Returns { merged: true } on success, or throws on failure.
+ */
+async function mergePR(octokit, { owner, repo, prNumber }) {
+  const { data } = await octokit.pulls.merge({
+    owner,
+    repo,
+    pull_number: prNumber,
+    merge_method: 'merge'
+  });
+  return data;
+}
+
 module.exports = {
   createClient,
   fetchRequiredChecks,
-  fetchPRState
+  fetchPRState,
+  mergePR
 };