prwatcher 2.0.0 → 2.2.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,11 @@ 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.2.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('--auto-rebase', 'automatically rebase PR branch when it falls behind (no conflicts only)')
   .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.2.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, rebasePR } = require('./github');
 const { sendNotification, formatMerged, formatClosed, formatCIFailed, formatRebaseNeeded, formatReady } = require('./slack');
 
 async function run(prUrl, options = {}) {
@@ -70,6 +70,12 @@ 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');
+  }
+  if (options.autoRebase) {
+    console.log('   ⚠  Auto-rebase is ON — PR branch will be updated automatically when behind (no conflicts only)');
+  }
   console.log('   Press Ctrl+C to stop\n');
 
   // 6. Poll function
@@ -111,12 +117,42 @@ async function run(prUrl, options = {}) {
 
       // Rebase needed
       if (state.mergeableState === 'behind' || state.mergeableState === 'dirty') {
-        if (lastState !== 'rebase_needed') {
-          console.log(`   🔄 ${timestamp} — Needs rebase (${state.mergeableState})`);
-          await sendNotification(config.slackWebhookUrl, formatRebaseNeeded(state.htmlUrl, state.title));
-          lastState = 'rebase_needed';
-        } else {
-          console.log(`   🔄 ${timestamp} — Still needs rebase (already notified)`);
+        if (state.mergeableState === 'dirty') {
+          // Has conflicts — can't auto-rebase, just notify
+          if (lastState !== 'rebase_needed') {
+            console.log(`   🔄 ${timestamp} — Needs rebase (has conflicts, manual fix required)`);
+            await sendNotification(config.slackWebhookUrl, formatRebaseNeeded(state.htmlUrl, state.title));
+            lastState = 'rebase_needed';
+          } else {
+            console.log(`   🔄 ${timestamp} — Still has conflicts (already notified)`);
+          }
+        } else if (state.mergeableState === 'behind') {
+          if (options.autoRebase) {
+            // No conflicts — safe to auto-rebase
+            try {
+              console.log(`   🔄 ${timestamp} — Auto-rebasing from ${state.baseBranch}...`);
+              await rebasePR(octokit, { owner, repo, prNumber });
+              console.log(`   ✅ ${timestamp} — Auto-rebased! Waiting for CI to re-run...`);
+              await sendNotification(config.slackWebhookUrl, `🔄 *PR branch auto-rebased from ${state.baseBranch}*\n<${state.htmlUrl}|${state.title}>\nCI will re-run on the updated branch.`);
+              lastState = null; // reset so we notify again after CI re-runs
+            } catch (rebaseError) {
+              const rebaseMsg = rebaseError.response?.data?.message || rebaseError.message;
+              const hint = rebaseError.status === 403
+                ? ' (GitHub token needs "Contents: Read and write" permission)'
+                : '';
+              console.error(`   ⚠  ${timestamp} — Auto-rebase failed: ${rebaseMsg}${hint}`);
+              await sendNotification(config.slackWebhookUrl, formatRebaseNeeded(state.htmlUrl, state.title));
+              lastState = 'rebase_needed';
+            }
+          } else {
+            if (lastState !== 'rebase_needed') {
+              console.log(`   🔄 ${timestamp} — Needs rebase (behind ${state.baseBranch})`);
+              await sendNotification(config.slackWebhookUrl, formatRebaseNeeded(state.htmlUrl, state.title));
+              lastState = 'rebase_needed';
+            } else {
+              console.log(`   🔄 ${timestamp} — Still behind (already notified)`);
+            }
+          }
         }
         return;
       }
@@ -127,12 +163,42 @@ 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)`);
         }
         return;
       }
 
+      // Blocked — CI passed but review approval required
+      if (state.mergeableState === 'blocked') {
+        if (lastState !== 'needs_review') {
+          console.log(`   👀 ${timestamp} — Waiting for review approval`);
+          await sendNotification(config.slackWebhookUrl, `👀 *PR is waiting for review approval*\n<${state.htmlUrl}|${state.title}>\nAll CI checks passed — needs at least 1 approving review to merge.`);
+          lastState = 'needs_review';
+        } else {
+          console.log(`   👀 ${timestamp} — Still waiting for review (already notified)`);
+        }
+        return;
+      }
+
       // Pending / other state
       const pending = state.checks ? state.checks.pendingRequired.length : 0;
       const total = state.checks ? state.checks.requiredTotal : 0;

package/src/github.js

@@ -115,8 +115,38 @@ 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;
+}
+
+/**
+ * Update (rebase) a PR branch with the latest from its base branch.
+ * Only works when mergeable_state is 'behind' (no conflicts).
+ * Throws if there are conflicts or insufficient permissions.
+ */
+async function rebasePR(octokit, { owner, repo, prNumber }) {
+  const { data } = await octokit.pulls.updateBranch({
+    owner,
+    repo,
+    pull_number: prNumber
+  });
+  return data;
+}
+
 module.exports = {
   createClient,
   fetchRequiredChecks,
-  fetchPRState
+  fetchPRState,
+  mergePR,
+  rebasePR
 };