prwatcher 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# prwatcher
+
+CLI tool that watches GitHub PRs and sends Slack notifications when CI passes, fails, or the PR is ready to merge.
+
+**Zero setup for developers** — just run one command. No Slack app creation, no servers, no ngrok.
+
+## Roadmap
+
+### Phase 1 — CLI Watcher (Done)
+Run from your terminal. Watches PRs and sends Slack notifications while your laptop is on.
+
+### Phase 2 — Cloud Watcher + Multi-Channel (Coming Soon)
+- Run without a laptop via GitHub Actions — completely free, auto-stops when PR is merged/closed
+- Multi-channel notifications: Telegram, Discord, Microsoft Teams
+
+---
+
+## Phase 1: CLI Watcher
+
+### Install
+
+```bash
+npm install -g prwatcher
+```
+
+Or use directly with npx:
+
+```bash
+npx prwatcher https://github.com/owner/repo/pull/123
+```
+
+### 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)
+
+These are saved to `~/.prwatcher` so you only enter them once.
+
+### Options
+
+```bash
+prwatcher <pr-url> [options]
+
+Options:
+  --interval <minutes>   Polling interval in minutes (default: 1)
+  --reset-config         Re-enter GitHub token and Slack webhook URL
+  -V, --version          Output version number
+  -h, --help             Display help
+```
+
+### Examples
+
+```bash
+# Watch a PR with default 1-minute polling
+prwatcher https://github.com/org/repo/pull/42
+
+# Poll every 30 seconds
+prwatcher https://github.com/org/repo/pull/42 --interval 0.5
+
+# Poll every 5 minutes
+prwatcher https://github.com/org/repo/pull/42 --interval 5
+
+# Re-enter credentials
+prwatcher https://github.com/org/repo/pull/42 --reset-config
+```
+
+### Notifications
+
+You'll get Slack messages when:
+
+| Event | Message |
+|-------|---------|
+| 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 merged | 🎉 PR was merged! |
+| PR is closed | ❌ PR was closed without merging |
+
+Notifications only fire on **state changes** — no spam.
+
+### Smart CI Detection
+
+The tool distinguishes between **required** and **optional** CI checks using GitHub's branch protection rules:
+
+- If a **required** check fails → you get notified
+- If an **optional** check fails → ignored, PR can still merge
+- If branch protection can't be read (no admin access) → falls back to treating all checks as required
+
+### One-Time Team Setup (Slack Webhook)
+
+One team member creates the webhook, shares the URL with everyone:
+
+1. Go to [Slack API → Apps](https://api.slack.com/apps)
+2. Create an app (or use existing) → **Incoming Webhooks** → Enable
+3. **Add New Webhook to Workspace** → pick your `#pr-notifications` channel
+4. Copy the webhook URL and share with your team
+
+Each developer pastes this URL on their first `prwatcher` run.
+
+### How It Works
+
+```
+prwatcher <url>
+     ↓
+Poll GitHub API every N seconds
+     ↓
+Detect state change (CI failed, ready, merged, etc.)
+     ↓
+POST to Slack webhook
+     ↓
+PR merged/closed? → exit
+```
+
+---
+
+## Phase 2 (Coming Soon)
+
+### Cloud Watcher
+> Watch PRs without keeping your laptop open.
+
+The CLI will trigger a **GitHub Actions workflow** that runs in the cloud on your behalf. It polls the PR on a schedule, sends notifications on state changes, and auto-stops when the PR is merged or closed.
+
+- Free (runs within GitHub Actions' 2,000 free minutes/month)
+- No server to manage
+- Works exactly like Phase 1, but in the cloud
+
+```bash
+prwatcher https://github.com/org/repo/pull/42 --cloud
+```
+
+### Multi-Channel Notifications
+> Not just Slack — get notified wherever your team lives.
+
+| Channel | Status |
+|---------|--------|
+| Slack | Done |
+| Telegram | Coming soon |
+| Discord | Coming soon |
+| Microsoft Teams | Coming soon |
+
+```bash
+prwatcher https://github.com/org/repo/pull/42
+# → Where do you want notifications?
+# → 1. Slack  2. Telegram  3. Discord  4. Microsoft Teams
+```
+
+---
+
+## License
+
+MIT

package/bin/watch-pr.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { run } = require('../src/cli');
+
+program
+  .name('prwatcher')
+  .description('Watch a GitHub PR and get Slack notifications on state changes')
+  .version('2.0.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('--reset-config', 're-enter GitHub token and Slack webhook URL')
+  .action((prUrl, options) => {
+    run(prUrl, options);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "prwatcher",
+  "version": "2.0.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": {
+    "prwatcher": "./bin/watch-pr.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node bin/watch-pr.js"
+  },
+  "keywords": [
+    "github",
+    "pr",
+    "ci",
+    "slack",
+    "watch",
+    "cli"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@octokit/rest": "^22.0.1",
+    "commander": "^14.0.3"
+  }
+}

package/src/cli.js

@@ -0,0 +1,175 @@
+const { parsePRUrl, buildPRKey } = require('./utils');
+const { ensureConfig } = require('./config');
+const { createClient, fetchRequiredChecks, fetchPRState } = require('./github');
+const { sendNotification, formatMerged, formatClosed, formatCIFailed, formatRebaseNeeded, formatReady } = require('./slack');
+
+async function run(prUrl, options = {}) {
+  // 1. Parse PR URL
+  const parsed = parsePRUrl(prUrl);
+  if (!parsed) {
+    console.error(`Invalid GitHub PR URL: ${prUrl}`);
+    console.error('Expected format: https://github.com/owner/repo/pull/123');
+    process.exit(1);
+  }
+
+  const { owner, repo, prNumber } = parsed;
+  const prKey = buildPRKey(owner, repo, prNumber);
+
+  // 2. Load or prompt for config
+  const config = await ensureConfig(options.resetConfig);
+
+  // 3. Initialize GitHub client
+  const octokit = createClient(config.githubToken);
+
+  // 4. Fetch required checks (once at startup)
+  console.log(`\n👀 Watching ${prKey}`);
+  console.log('   Fetching branch protection rules...');
+
+  let requiredCheckNames = null;
+
+  // We need to know the base branch first — do an initial PR fetch
+  try {
+    const initialState = await fetchPRState(octokit, { owner, repo, prNumber, requiredCheckNames: null });
+
+    if (initialState.closed) {
+      const status = initialState.merged ? 'already merged' : 'already closed';
+      console.log(`\n   PR is ${status}. Nothing to watch.`);
+      process.exit(0);
+    }
+
+    requiredCheckNames = await fetchRequiredChecks(octokit, {
+      owner,
+      repo,
+      branch: initialState.baseBranch
+    });
+
+    if (requiredCheckNames) {
+      console.log(`   ✅ Found ${requiredCheckNames.size} required check(s): ${[...requiredCheckNames].join(', ')}`);
+    } else {
+      console.log('   ℹ  Could not fetch branch protection rules. Treating all checks as required.');
+    }
+  } catch (error) {
+    const msg = error.status
+      ? `GitHub API error ${error.status}: ${error.response?.data?.message || 'Server error'}`
+      : error.message.length > 200
+        ? error.message.slice(0, 200) + '...'
+        : error.message;
+    console.error(`\n   Failed to fetch PR: ${msg}`);
+    if (error.status === 401) {
+      console.error('   Your GitHub token may be invalid. Run with --reset-config to re-enter it.');
+    }
+    if (error.status === 404) {
+      console.error('   PR not found. Check the URL and ensure your token has access to this repo.');
+    }
+    process.exit(1);
+  }
+
+  // 5. State tracking
+  let lastState = null;
+  const intervalMinutes = parseFloat(options.interval) || 1;
+  const intervalMs = intervalMinutes * 60 * 1000;
+
+  console.log(`   Polling every ${intervalMinutes >= 1 ? `${intervalMinutes} minute(s)` : `${intervalMinutes * 60} seconds`}`);
+  console.log('   Press Ctrl+C to stop\n');
+
+  // 6. Poll function
+  async function poll() {
+    try {
+      const state = await fetchPRState(octokit, { owner, repo, prNumber, requiredCheckNames });
+      const timestamp = new Date().toLocaleTimeString();
+
+      // PR merged
+      if (state.closed && state.merged) {
+        console.log(`   🎉 ${timestamp} — Merged!`);
+        await sendNotification(config.slackWebhookUrl, formatMerged(state.htmlUrl, state.title));
+        cleanup();
+        process.exit(0);
+        return;
+      }
+
+      // PR closed
+      if (state.closed && !state.merged) {
+        console.log(`   ❌ ${timestamp} — Closed without merging`);
+        await sendNotification(config.slackWebhookUrl, formatClosed(state.htmlUrl, state.title));
+        cleanup();
+        process.exit(0);
+        return;
+      }
+
+      // CI failed (required checks only)
+      if (state.checks && state.checks.failedRequired.length > 0) {
+        if (lastState !== 'ci_failed') {
+          const failedNames = state.checks.failedRequired.map(c => c.name);
+          console.log(`   ⚠️  ${timestamp} — Required CI checks failed: ${failedNames.join(', ')}`);
+          await sendNotification(config.slackWebhookUrl, formatCIFailed(state.htmlUrl, state.title, failedNames));
+          lastState = 'ci_failed';
+        } else {
+          console.log(`   ⚠️  ${timestamp} — CI still failing (already notified)`);
+        }
+        return;
+      }
+
+      // 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)`);
+        }
+        return;
+      }
+
+      // Ready to merge
+      if (state.mergeableState === 'clean') {
+        if (lastState !== 'ready') {
+          console.log(`   ✅ ${timestamp} — Ready to merge!`);
+          await sendNotification(config.slackWebhookUrl, formatReady(state.htmlUrl, state.title));
+          lastState = 'ready';
+        } else {
+          console.log(`   ✅ ${timestamp} — Still ready (already notified)`);
+        }
+        return;
+      }
+
+      // Pending / other state
+      const pending = state.checks ? state.checks.pendingRequired.length : 0;
+      const total = state.checks ? state.checks.requiredTotal : 0;
+      console.log(`   ⏳ ${timestamp} — CI running (${total - pending}/${total} required checks done, mergeable: ${state.mergeableState || 'unknown'})`);
+
+    } catch (error) {
+      const timestamp = new Date().toLocaleTimeString();
+      const msg = error.status
+        ? `GitHub API error ${error.status}: ${error.response?.data?.message || 'Server error (retrying next poll)'}`
+        : error.message.length > 200
+          ? error.message.slice(0, 200) + '...'
+          : error.message;
+      console.error(`   ⚠  ${timestamp} — ${msg}`);
+    }
+  }
+
+  // 7. Graceful shutdown
+  let intervalId;
+
+  function cleanup() {
+    if (intervalId) clearInterval(intervalId);
+  }
+
+  process.on('SIGINT', () => {
+    console.log('\n\n   Stopped watching. Bye!');
+    cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  // 8. Run immediately, then on interval
+  await poll();
+  intervalId = setInterval(poll, intervalMs);
+}
+
+module.exports = { run };

package/src/config.js

@@ -0,0 +1,86 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const CONFIG_PATH = path.join(os.homedir(), '.watch-pr');
+
+function loadConfig() {
+  try {
+    const data = fs.readFileSync(CONFIG_PATH, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+function saveConfig(config) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+function prompt(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function promptForConfig(existing = {}) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  const config = { ...existing };
+
+  try {
+    if (!config.githubToken) {
+      console.error('\n⚠ GitHub token not found.');
+      console.error('  Create one at: https://github.com/settings/tokens');
+      console.error('  Required scope: repo\n');
+      config.githubToken = await prompt(rl, 'Paste your GitHub personal access token: ');
+      if (!config.githubToken) {
+        console.error('GitHub token is required.');
+        process.exit(1);
+      }
+    }
+
+    if (!config.slackWebhookUrl) {
+      console.error('\n⚠ Slack webhook URL not found.');
+      console.error('  Create one at: https://api.slack.com/apps → Incoming Webhooks\n');
+      config.slackWebhookUrl = await prompt(rl, 'Paste your Slack Incoming Webhook URL: ');
+      if (!config.slackWebhookUrl) {
+        console.error('Slack webhook URL is required.');
+        process.exit(1);
+      }
+      if (!config.slackWebhookUrl.startsWith('https://hooks.slack.com/')) {
+        console.error('Invalid Slack webhook URL. It should start with https://hooks.slack.com/');
+        process.exit(1);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  return config;
+}
+
+async function ensureConfig(forceReset = false) {
+  let config = forceReset ? null : loadConfig();
+
+  if (!config || !config.githubToken || !config.slackWebhookUrl) {
+    config = await promptForConfig(config || {});
+    saveConfig(config);
+    console.error('✅ Config saved to ~/.watch-pr\n');
+  }
+
+  return config;
+}
+
+module.exports = {
+  ensureConfig,
+  loadConfig,
+  saveConfig,
+  CONFIG_PATH
+};

package/src/github.js

@@ -0,0 +1,122 @@
+const { Octokit } = require('@octokit/rest');
+
+function createClient(token) {
+  return new Octokit({ auth: token });
+}
+
+/**
+ * Fetch required status checks from branch protection rules.
+ * Returns array of required check names, or null if unavailable (no permissions or no protection).
+ */
+async function fetchRequiredChecks(octokit, { owner, repo, branch }) {
+  try {
+    const { data } = await octokit.repos.getBranchProtection({
+      owner,
+      repo,
+      branch
+    });
+
+    const checks = data.required_status_checks;
+    if (!checks) return null;
+
+    // GitHub API returns checks in both `contexts` (legacy) and `checks` (new)
+    const requiredNames = new Set();
+
+    if (checks.checks && checks.checks.length > 0) {
+      checks.checks.forEach(c => requiredNames.add(c.context));
+    }
+
+    if (checks.contexts && checks.contexts.length > 0) {
+      checks.contexts.forEach(c => requiredNames.add(c));
+    }
+
+    return requiredNames.size > 0 ? requiredNames : null;
+  } catch {
+    // 403 (no permissions) or 404 (no branch protection) — fall back
+    return null;
+  }
+}
+
+/**
+ * Fetch PR data and CI check runs, then classify the state.
+ */
+async function fetchPRState(octokit, { owner, repo, prNumber, requiredCheckNames }) {
+  // Fetch PR details
+  const { data: pr } = await octokit.pulls.get({
+    owner,
+    repo,
+    pull_number: prNumber
+  });
+
+  // If PR is closed, no need to check CI
+  if (pr.state === 'closed') {
+    return {
+      merged: pr.merged,
+      closed: true,
+      htmlUrl: pr.html_url,
+      title: pr.title,
+      baseBranch: pr.base.ref,
+      headSha: pr.head.sha,
+      mergeableState: pr.mergeable_state,
+      checks: null
+    };
+  }
+
+  // Fetch check runs for the head SHA
+  const { data: checkRunsData } = await octokit.checks.listForRef({
+    owner,
+    repo,
+    ref: pr.head.sha
+  });
+
+  // Deduplicate check runs — GitHub returns multiple runs for the same check name
+  // (e.g. re-runs). Keep only the latest run per check name.
+  const latestByName = new Map();
+  for (const check of checkRunsData.check_runs) {
+    const existing = latestByName.get(check.name);
+    if (!existing || new Date(check.started_at) > new Date(existing.started_at)) {
+      latestByName.set(check.name, check);
+    }
+  }
+
+  // Classify each check as required or not
+  const checks = [...latestByName.values()].map(check => {
+    const isRequired = requiredCheckNames
+      ? requiredCheckNames.has(check.name)
+      : true; // if we don't know required checks, treat all as required
+
+    return {
+      name: check.name,
+      status: check.status,         // queued, in_progress, completed
+      conclusion: check.conclusion, // success, failure, neutral, etc.
+      required: isRequired
+    };
+  });
+
+  const requiredChecks = checks.filter(c => c.required);
+  const failedRequired = requiredChecks.filter(c => c.conclusion === 'failure');
+  const pendingRequired = requiredChecks.filter(c => c.status !== 'completed');
+
+  return {
+    merged: false,
+    closed: false,
+    htmlUrl: pr.html_url,
+    title: pr.title,
+    baseBranch: pr.base.ref,
+    headSha: pr.head.sha,
+    mergeableState: pr.mergeable_state,
+    checks: {
+      all: checks,
+      requiredTotal: requiredChecks.length,
+      failedRequired,
+      pendingRequired,
+      allRequiredPassed: failedRequired.length === 0 && pendingRequired.length === 0 && requiredChecks.length > 0
+    }
+  };
+}
+
+module.exports = {
+  createClient,
+  fetchRequiredChecks,
+  fetchPRState
+};

package/src/slack.js

@@ -0,0 +1,45 @@
+async function sendNotification(webhookUrl, text) {
+  try {
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text })
+    });
+
+    if (!response.ok) {
+      console.error(`Slack notification failed: ${response.status} ${response.statusText}`);
+    }
+  } catch (error) {
+    console.error(`Slack notification error: ${error.message}`);
+  }
+}
+
+function formatMerged(prUrl, title) {
+  return `🎉 *PR was merged!*\n<${prUrl}|${title}>`;
+}
+
+function formatClosed(prUrl, title) {
+  return `❌ *PR was closed without merging*\n<${prUrl}|${title}>`;
+}
+
+function formatCIFailed(prUrl, title, failedChecks) {
+  const checkList = failedChecks.map(c => `  • ${c}`).join('\n');
+  return `⚠️ *CI checks failed*\n<${prUrl}|${title}>\n\nFailed required checks:\n${checkList}`;
+}
+
+function formatRebaseNeeded(prUrl, title) {
+  return `🔄 *PR needs rebase*\n<${prUrl}|${title}>`;
+}
+
+function formatReady(prUrl, title) {
+  return `✅ *PR is ready to merge!*\n<${prUrl}|${title}>`;
+}
+
+module.exports = {
+  sendNotification,
+  formatMerged,
+  formatClosed,
+  formatCIFailed,
+  formatRebaseNeeded,
+  formatReady
+};

package/src/utils.js

@@ -0,0 +1,38 @@
+/**
+ * Parse GitHub PR URL into components
+ * @param {string} url - GitHub PR URL (e.g., https://github.com/owner/repo/pull/123)
+ * @returns {object|null} - {owner, repo, prNumber} or null if invalid
+ */
+function parsePRUrl(url) {
+  if (!url || typeof url !== 'string') {
+    return null;
+  }
+
+  const match = url.match(/github\.com\/([^\/]+)\/([^\/]+)\/pull\/(\d+)/);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    owner: match[1],
+    repo: match[2],
+    prNumber: parseInt(match[3], 10)
+  };
+}
+
+/**
+ * Build PR key for storage
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number} prNumber - PR number
+ * @returns {string} - PR key (e.g., "owner/repo#123")
+ */
+function buildPRKey(owner, repo, prNumber) {
+  return `${owner}/${repo}#${prNumber}`;
+}
+
+module.exports = {
+  parsePRUrl,
+  buildPRKey
+};