@in-the-loop-labs/pair-review 2.6.3 → 3.0.0

package/src/local-scope.js

@@ -0,0 +1,58 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+const STOPS = ['branch', 'staged', 'unstaged', 'untracked'];
+
+const DEFAULT_SCOPE = { start: 'unstaged', end: 'untracked' };
+
+function isValidScope(start, end) {
+  const si = STOPS.indexOf(start);
+  const ei = STOPS.indexOf(end);
+  return si !== -1 && ei !== -1 && si <= ei;
+}
+
+function scopeIncludes(start, end, stop) {
+  if (!isValidScope(start, end)) return false;
+  const si = STOPS.indexOf(start);
+  const ei = STOPS.indexOf(end);
+  const ti = STOPS.indexOf(stop);
+  return ti !== -1 && ti >= si && ti <= ei;
+}
+
+function includesBranch(start) {
+  return start === 'branch';
+}
+
+function fromLegacyMode(localMode) {
+  if (localMode === 'uncommitted') {
+    return { start: 'unstaged', end: 'untracked' };
+  }
+  if (localMode === 'branch') {
+    return { start: 'branch', end: 'branch' };
+  }
+  return { start: DEFAULT_SCOPE.start, end: DEFAULT_SCOPE.end };
+}
+
+function scopeLabel(start, end) {
+  if (!isValidScope(start, end)) return '';
+  const label = s => s.charAt(0).toUpperCase() + s.slice(1);
+  if (start === end) return label(start);
+  return `${label(start)}\u2013${label(end)}`;
+}
+
+const LocalScope = {
+  STOPS,
+  DEFAULT_SCOPE,
+  isValidScope,
+  scopeIncludes,
+  includesBranch,
+  fromLegacyMode,
+  scopeLabel,
+};
+
+if (typeof window !== 'undefined') {
+  window.LocalScope = LocalScope;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = LocalScope;
+}

package/src/main.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const fs = require('fs');
 const { loadConfig, getConfigDir, getGitHubToken, showWelcomeMessage, resolveDbName, resolveMonorepoOptions } = require('./config');
 const { initializeDatabase, run, queryOne, query, migrateExistingWorktrees, WorktreeRepository, ReviewRepository, RepoSettingsRepository, GitHubReviewRepository } = require('./database');
@@ -10,6 +10,7 @@ const Analyzer = require('./ai/analyzer');
 const { applyConfigOverrides } = require('./ai');
 const { handleLocalReview, findMainGitRoot } = require('./local-review');
 const { storePRData, registerRepositoryLocation, findRepositoryPath } = require('./setup/pr-setup');
+const { fireReviewStartedHook } = require('./hooks/payloads');
 const { normalizeRepository, resolveRenamedFile, resolveRenamedFileOld } = require('./utils/paths');
 const logger = require('./utils/logger');
 const simpleGit = require('simple-git');
@@ -182,6 +183,41 @@ function cleanupStaleWorktreesAsync(config) {
   });
 }
 
+/**
+ * Asynchronously cleanup stale reviews (runs in background, doesn't block)
+ * @param {Object} config - Application configuration
+ */
+function cleanupStaleReviewsAsync(config) {
+  setImmediate(async () => {
+    try {
+      const retentionDays = config.review_retention_days || 21;
+      const cutoffDate = new Date();
+      cutoffDate.setDate(cutoffDate.getDate() - retentionDays);
+      const cutoffISO = cutoffDate.toISOString();
+
+      const reviewRepo = new ReviewRepository(db);
+      const staleReviews = await reviewRepo.findStale(cutoffISO);
+
+      if (staleReviews.length === 0) return;
+
+      logger.info(`[pair-review] Cleaning up ${staleReviews.length} reviews older than ${retentionDays} days`);
+
+      for (const review of staleReviews) {
+        try {
+          await reviewRepo.deleteWithRelatedData(review.id, {
+            prNumber: review.pr_number,
+            repository: review.repository
+          });
+        } catch (err) {
+          logger.error(`[pair-review] Failed to cleanup review ${review.id}: ${err.message}`);
+        }
+      }
+    } catch (error) {
+      logger.error('[pair-review] Background review cleanup error:', error.message);
+    }
+  });
+}
+
 // Known flags that are valid (for validation)
 const KNOWN_FLAGS = new Set([
   '--ai',
@@ -436,6 +472,11 @@ AI PROVIDERS:
       // Resolve localPath, defaulting to cwd if not provided
       const targetPath = flags.localPath || process.cwd();
       await handleLocalReview(targetPath, flags);
+
+      // Async cleanup of stale worktrees and reviews (don't block startup)
+      cleanupStaleWorktreesAsync(config);
+      cleanupStaleReviewsAsync(config);
+
       return; // Exit after local review
     }
 
@@ -531,8 +572,9 @@ async function handlePullRequest(args, config, db, flags = {}) {
     // Start server and open browser to setup page
     const port = await startServer(db);
 
-    // Async cleanup of stale worktrees (don't block startup)
+    // Async cleanup of stale worktrees and reviews (don't block startup)
     cleanupStaleWorktreesAsync(config);
+    cleanupStaleReviewsAsync(config);
 
     let url = `http://localhost:${port}/pr/${prInfo.owner}/${prInfo.repo}/${prInfo.number}`;
     if (flags.ai) {
@@ -555,8 +597,9 @@ async function handlePullRequest(args, config, db, flags = {}) {
 async function startServerOnly(config) {
   const port = await startServer(db);
 
-  // Async cleanup of stale worktrees (don't block startup)
+  // Async cleanup of stale worktrees and reviews (don't block startup)
   cleanupStaleWorktreesAsync(config);
+  cleanupStaleReviewsAsync(config);
 
   // Open browser to landing page
   const url = `http://localhost:${port}/`;
@@ -744,10 +787,18 @@ async function performHeadlessReview(args, config, db, flags, options) {
 
     // Store PR data in database
     console.log('Storing pull request data...');
-    await storePRData(db, prInfo, prData, diff, changedFiles, worktreePath, {
+    const { isNewReview, reviewId: storedReviewId } = await storePRData(db, prInfo, prData, diff, changedFiles, worktreePath, {
       skipWorktreeRecord: !!flags.useCheckout
     });
 
+    // Fire review.started hook for new reviews (non-blocking)
+    if (isNewReview) {
+      fireReviewStartedHook({
+        reviewId: storedReviewId, prNumber: prInfo.number,
+        owner: prInfo.owner, repo: prInfo.repo, prData, config,
+      }).catch(err => { logger.warn(`Review hook failed: ${err.message}`); });
+    }
+
     // Get PR metadata ID for AI analysis
     const prMetadata = await queryOne(db, `
       SELECT id, pr_data FROM pr_metadata
@@ -764,7 +815,7 @@ async function performHeadlessReview(args, config, db, flags, options) {
     // The review.id is passed to the analyzer so comments use review.id, not prMetadata.id
     // This avoids ID collision with local mode where comments also use reviews.id
     const reviewRepo = new ReviewRepository(db);
-    const review = await reviewRepo.getOrCreate({ prNumber: prInfo.number, repository });
+    const { review } = await reviewRepo.getOrCreate({ prNumber: prInfo.number, repository });
 
     // Fetch repo settings to get default instructions
     const repoSettingsRepo = new RepoSettingsRepository(db);

package/src/mcp-stdio.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * MCP stdio transport orchestrator.
  *

package/src/protocol-handler.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');

package/src/routes/analyses.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * AI Analysis Routes (shared, ID-based endpoints)
  *
@@ -21,6 +21,8 @@ const { getTierForModel } = require('../ai/provider');
 const { v4: uuidv4 } = require('uuid');
 const logger = require('../utils/logger');
 const { broadcastReviewEvent } = require('../events/review-events');
+const { fireHooks, hasHooks } = require('../hooks/hook-runner');
+const { buildAnalysisStartedPayload, buildAnalysisCompletedPayload, getCachedUser } = require('../hooks/payloads');
 const path = require('path');
 const { normalizeRepository } = require('../utils/paths');
 const {
@@ -31,7 +33,7 @@ const {
   killProcesses,
   createProgressCallback
 } = require('./shared');
-const { generateLocalDiff, computeLocalDiffDigest } = require('../local-review');
+const { generateLocalDiff, computeLocalDiffDigest, getCurrentBranch } = require('../local-review');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
 
@@ -209,13 +211,21 @@ router.post('/api/analyses/results', async (req, res) => {
     // --- Resolve review ---
     let reviewId;
     if (hasLocal) {
-      // Local mode: derive repository name from the directory basename
-      const repository = path.basename(localPath) || 'local';
-      reviewId = await reviewRepo.upsertLocalReview({
-        localPath,
-        localHeadSha: headSha,
-        repository
-      });
+      // Local mode: find existing session or create a new one
+      let localHeadBranch;
+      try { localHeadBranch = await getCurrentBranch(localPath); } catch (_) { /* non-fatal */ }
+      const existingReview = await reviewRepo.findLocalReview(localPath, headSha, localHeadBranch);
+      if (existingReview) {
+        reviewId = existingReview.id;
+      } else {
+        const repository = path.basename(localPath) || 'local';
+        reviewId = await reviewRepo.upsertLocalReview({
+          localPath,
+          localHeadSha: headSha,
+          repository,
+          localHeadBranch
+        });
+      }
 
       // Generate and store diff so the web UI can display it
       try {
@@ -235,7 +245,7 @@ router.post('/api/analyses/results', async (req, res) => {
         return res.status(400).json({ error: 'Invalid pull request number' });
       }
       const repository = normalizeRepository(repoParts[0], repoParts[1]);
-      const review = await reviewRepo.getOrCreate({
+      const { review } = await reviewRepo.getOrCreate({
         prNumber: parsedPR,
         repository
       });
@@ -395,6 +405,10 @@ router.post('/api/analyses/:id/cancel', async (req, res) => {
     // Broadcast cancelled status to WebSocket clients
     broadcastProgress(id, cancelledStatus);
 
+    // Hook firing removed — the .catch(isCancellation) handlers in
+    // pr.js, local.js, and launchCouncilAnalysis already fire
+    // analysis.completed with full context when the process exits.
+
     // Clean up review to analysis ID mapping
     if (analysis.reviewId) {
       reviewToAnalysisId.delete(analysis.reviewId);
@@ -453,7 +467,9 @@ async function launchCouncilAnalysis(db, modeContext, councilConfig, councilId,
     logLabel,
     initialStatusExtra,
     onSuccess,
-    runUpdateExtra
+    runUpdateExtra,
+    config: modeConfig,
+    hookContext = {},
   } = modeContext;
 
   const { repoInstructions, requestInstructions } = instructions;
@@ -521,6 +537,17 @@ async function launchCouncilAnalysis(db, modeContext, councilConfig, councilId,
 
   broadcastProgress(analysisId, initialStatus);
   broadcastReviewEvent(reviewId, { type: 'review:analysis_started', analysisId });
+  const effectiveConfig = modeConfig || {};
+  if (hasHooks('analysis.started', effectiveConfig)) {
+    getCachedUser(effectiveConfig).then(user => {
+      fireHooks('analysis.started', buildAnalysisStartedPayload({
+        reviewId, analysisId, provider: 'council', model: councilId || 'inline-config',
+        mode: initialStatusExtra?.reviewType || 'pr',
+        prContext: hookContext.prContext, localContext: hookContext.localContext,
+        user,
+      }), effectiveConfig);
+    }).catch(err => { logger.warn(`Analysis hook failed: ${err.message}`); });
+  }
 
   const analyzer = new Analyzer(db, 'council', 'council');
 
@@ -588,10 +615,34 @@ async function launchCouncilAnalysis(db, modeContext, councilConfig, councilId,
       activeAnalyses.set(analysisId, completedStatus);
       broadcastProgress(analysisId, completedStatus);
       broadcastReviewEvent(initialStatus.reviewId, { type: 'review:analysis_completed' });
+
+      // Fire analysis.completed hook
+      if (hasHooks('analysis.completed', effectiveConfig)) {
+        getCachedUser(effectiveConfig).then(user => {
+          fireHooks('analysis.completed', buildAnalysisCompletedPayload({
+            reviewId: initialStatus.reviewId, analysisId, provider: 'council',
+            model: councilId || 'inline-config',
+            status: 'success', totalSuggestions: result.suggestions.length,
+            mode: initialStatusExtra?.reviewType || 'pr',
+            prContext: hookContext.prContext, localContext: hookContext.localContext, user,
+          }), effectiveConfig);
+        }).catch(() => {});
+      }
     })
     .catch(error => {
       if (error.isCancellation) {
         logger.info(`Council analysis cancelled for ${logLabel}`);
+        if (hasHooks('analysis.completed', effectiveConfig)) {
+          getCachedUser(effectiveConfig).then(user => {
+            fireHooks('analysis.completed', buildAnalysisCompletedPayload({
+              reviewId, analysisId, provider: 'council',
+              model: councilId || 'inline-config',
+              status: 'cancelled', totalSuggestions: 0,
+              mode: initialStatusExtra?.reviewType || 'pr',
+              prContext: hookContext.prContext, localContext: hookContext.localContext, user,
+            }), effectiveConfig);
+          }).catch(() => {});
+        }
         return;
       }
       logger.error(`Council analysis failed for ${logLabel}: ${error.message}`);
@@ -607,6 +658,18 @@ async function launchCouncilAnalysis(db, modeContext, councilConfig, councilId,
       broadcastProgress(analysisId, failedStatus);
 
       analysisRunRepo.update(runId, { status: 'failed' }).catch(() => {});
+
+      if (hasHooks('analysis.completed', effectiveConfig)) {
+        getCachedUser(effectiveConfig).then(user => {
+          fireHooks('analysis.completed', buildAnalysisCompletedPayload({
+            reviewId, analysisId, provider: 'council',
+            model: councilId || 'inline-config',
+            status: 'failed', totalSuggestions: 0,
+            mode: initialStatusExtra?.reviewType || 'pr',
+            prContext: hookContext.prContext, localContext: hookContext.localContext, user,
+          }), effectiveConfig);
+        }).catch(() => {});
+      }
     })
     .finally(() => {
       // Clean up unified tracking map entry

package/src/routes/chat.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * Chat Routes
  *
@@ -18,6 +18,32 @@ const { renderApiDocs, buildApiCheatSheet } = require('../chat/api-reference');
 const { GitWorktreeManager } = require('../git/worktree');
 const logger = require('../utils/logger');
 const ws = require('../ws');
+const { fireHooks, hasHooks } = require('../hooks/hook-runner');
+const { buildChatStartedPayload, buildChatResumedPayload, buildChatHookContext, getCachedUser } = require('../hooks/payloads');
+
+/**
+ * Fire a chat hook event (non-blocking). Skips async work when no hooks are configured.
+ * @param {string} event - 'chat.started' or 'chat.resumed'
+ * @param {Object} opts
+ * @param {Object} opts.req - Express request (used to read config)
+ * @param {Object} opts.review - Review record
+ * @param {number} opts.sessionId - Chat session ID
+ * @param {string} opts.provider - AI provider
+ * @param {string} opts.model - AI model
+ */
+function fireChatHook(event, { req, review, sessionId, provider, model }) {
+  const config = req.app.get('config') || {};
+  if (!hasHooks(event, config)) return;
+
+  const buildPayload = event === 'chat.started' ? buildChatStartedPayload : buildChatResumedPayload;
+  getCachedUser(config).then(user => {
+    const payload = buildPayload({
+      reviewId: review.id, sessionId, provider, model,
+      ...buildChatHookContext(review), user,
+    });
+    fireHooks(event, payload, config);
+  }).catch(err => { logger.warn(`Chat hook failed: ${err.message}`); });
+}
 
 const router = express.Router();
 
@@ -302,6 +328,8 @@ router.post('/api/chat/session', async (req, res) => {
     // Register broadcast listeners so events reach all connected clients
     registerChatBroadcast(chatSessionManager, session.id, serverPort);
 
+    fireChatHook('chat.started', { req, review, sessionId: session.id, provider, model });
+
     const responseData = { id: session.id, status: session.status };
 
     // Include analysis context metadata so the frontend can show a context indicator
@@ -372,6 +400,8 @@ router.post('/api/chat/session/:id/message', async (req, res) => {
         registerChatBroadcast(chatSessionManager, sessionId, req.socket.localPort);
         logger.info(`[ChatRoute] Auto-resumed session ${sessionId} for message delivery`);
 
+        fireChatHook('chat.resumed', { req, review, sessionId, provider: session.provider, model: session.model });
+
         // Inject port correction so the agent knows the current server address,
         // even if the conversational history has a stale port from session creation.
         const serverPort = req.socket.localPort;
@@ -518,6 +548,9 @@ router.post('/api/chat/session/:id/resume', async (req, res) => {
     );
 
     logger.info(`[ChatRoute] Explicitly resumed session ${sessionId}`);
+
+    fireChatHook('chat.resumed', { req, review, sessionId, provider: session.provider, model: session.model });
+
     res.json({ data: { id: sessionId, status: 'active' } });
   } catch (error) {
     logger.error(`Error resuming chat session: ${error.message}`);

package/src/routes/config.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * Configuration Routes
  *
@@ -56,6 +56,7 @@ router.get('/api/config', (req, res) => {
     pi_available: getCachedAvailability('pi')?.available || false,
     assisted_by_url: config.assisted_by_url || 'https://github.com/in-the-loop-labs/pair-review',
     enable_graphite: config.enable_graphite === true,
+    chat_spinner: config.chat_spinner || 'dots',
     // Share configuration for external review viewers.
     // - url: The base URL of the external share site
     // - method: Plumbed through for future use (e.g., POST-based share flows).

package/src/routes/context-files.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * Context Files Routes
  *

package/src/routes/councils.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * Council Routes
  *

package/src/routes/github-collections.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * GitHub Collections Routes
  *