@in-the-loop-labs/pair-review 2.2.0 → 2.3.0

package/src/routes/setup.js

@@ -2,19 +2,17 @@
 /**
  * Setup Routes
  *
- * Provides API endpoints for the auto-create review flow with SSE progress
- * updates. Supports both PR-based and local review setup.
+ * Provides API endpoints for the auto-create review flow with WebSocket
+ * progress updates. Supports both PR-based and local review setup.
  *
  * Endpoints:
  * - POST /api/setup/pr/:owner/:repo/:number  - Start PR review setup
- * - GET  /api/setup/pr/:owner/:repo/:number/progress - SSE progress for PR setup
  * - POST /api/setup/local                     - Start local review setup
- * - GET  /api/setup/local/:setupId/progress   - SSE progress for local setup
  */
 
 const express = require('express');
 const crypto = require('crypto');
-const { activeSetups, setupProgressClients, broadcastSetupProgress } = require('./shared');
+const { activeSetups, broadcastSetupProgress } = require('./shared');
 const { setupPRReview } = require('../setup/pr-setup');
 const { setupLocalReview } = require('../setup/local-setup');
 const { getGitHubToken } = require('../config');
@@ -25,31 +23,17 @@ const logger = require('../utils/logger');
 const router = express.Router();
 
 /**
- * Send a named SSE event to all clients listening for a given setupId.
+ * Send a setup progress event via WebSocket.
  *
- * Unlike broadcastSetupProgress (which sends unnamed `data:` lines), this
- * helper emits SSE named events (`event: <type>\n`) so the frontend
- * EventSource `addEventListener(type, ...)` listeners fire correctly.
+ * Converts the named event pattern to a WebSocket message with a `type`
+ * field so the client can dispatch on `msg.type` (e.g. 'step', 'complete', 'error').
  *
  * @param {string} setupId - Setup operation ID
- * @param {string} eventType - SSE event name (e.g. 'step', 'complete', 'error')
+ * @param {string} eventType - Event type (e.g. 'step', 'complete', 'error')
  * @param {Object} data - JSON-serialisable payload
  */
-function sendSetupSSE(setupId, eventType, data) {
-  const clients = setupProgressClients.get(setupId);
-  if (clients && clients.size > 0) {
-    const message = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
-    clients.forEach(client => {
-      try {
-        client.write(message);
-      } catch (e) {
-        clients.delete(client);
-      }
-    });
-    if (clients.size === 0) {
-      setupProgressClients.delete(setupId);
-    }
-  }
+function sendSetupEvent(setupId, eventType, data) {
+  broadcastSetupProgress(setupId, { type: eventType, ...data });
 }
 
 // ---------------------------------------------------------------------------
@@ -60,7 +44,7 @@ function sendSetupSSE(setupId, eventType, data) {
  * Initiate an asynchronous PR review setup.
  *
  * Returns immediately with a { setupId } that the client uses to subscribe
- * to SSE progress events. If setup is already in-flight for this PR, the
+ * to WebSocket progress events. If setup is already in-flight for this PR, the
  * existing setupId is returned. If the PR already exists in the database the
  * response includes `{ existing: true, reviewUrl }` so the client can
  * navigate directly.
@@ -125,14 +109,14 @@ router.post('/api/setup/pr/:owner/:repo/:number', async (req, res) => {
           githubToken,
           config,
           onProgress: (progress) => {
-            sendSetupSSE(setupId, 'step', progress);
+            sendSetupEvent(setupId, 'step', progress);
           }
         });
 
-        sendSetupSSE(setupId, 'complete', { reviewUrl: result.reviewUrl, title: result.title });
+        sendSetupEvent(setupId, 'complete', { reviewUrl: result.reviewUrl, title: result.title });
       } catch (err) {
         logger.error(`PR setup failed for ${setupKey}:`, err);
-        sendSetupSSE(setupId, 'error', { message: err.message });
+        sendSetupEvent(setupId, 'error', { message: err.message });
       } finally {
         activeSetups.delete(setupKey);
       }
@@ -147,48 +131,6 @@ router.post('/api/setup/pr/:owner/:repo/:number', async (req, res) => {
   }
 });
 
-// ---------------------------------------------------------------------------
-// GET /api/setup/pr/:owner/:repo/:number/progress
-// ---------------------------------------------------------------------------
-
-/**
- * SSE endpoint for streaming PR setup progress to the client.
- *
- * The client must pass `?setupId=<id>` as a query parameter (returned from
- * the POST endpoint above).
- */
-router.get('/api/setup/pr/:owner/:repo/:number/progress', (req, res) => {
-  const { setupId } = req.query;
-
-  if (!setupId) {
-    return res.status(400).json({ error: 'Missing setupId query parameter' });
-  }
-
-  // SSE headers
-  res.writeHead(200, {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection': 'keep-alive'
-  });
-
-  // Register this client
-  if (!setupProgressClients.has(setupId)) {
-    setupProgressClients.set(setupId, new Set());
-  }
-  setupProgressClients.get(setupId).add(res);
-
-  // Clean up on disconnect
-  req.on('close', () => {
-    const clients = setupProgressClients.get(setupId);
-    if (clients) {
-      clients.delete(res);
-      if (clients.size === 0) {
-        setupProgressClients.delete(setupId);
-      }
-    }
-  });
-});
-
 // ---------------------------------------------------------------------------
 // POST /api/setup/local
 // ---------------------------------------------------------------------------
@@ -197,7 +139,7 @@ router.get('/api/setup/pr/:owner/:repo/:number/progress', (req, res) => {
  * Initiate an asynchronous local review setup.
  *
  * Expects JSON body `{ path }` with the local directory to review. Returns
- * `{ setupId }` for the client to subscribe to SSE progress events.
+ * `{ setupId }` for the client to subscribe to WebSocket progress events.
  */
 router.post('/api/setup/local', async (req, res) => {
   try {
@@ -224,11 +166,11 @@ router.post('/api/setup/local', async (req, res) => {
           db,
           targetPath,
           onProgress: (progress) => {
-            sendSetupSSE(setupId, 'step', progress);
+            sendSetupEvent(setupId, 'step', progress);
           }
         });
 
-        sendSetupSSE(setupId, 'complete', {
+        sendSetupEvent(setupId, 'complete', {
           reviewUrl: result.reviewUrl,
           reviewId: result.reviewId,
           existing: result.existing,
@@ -237,7 +179,7 @@ router.post('/api/setup/local', async (req, res) => {
         });
       } catch (err) {
         logger.error(`Local setup failed for ${setupKey}:`, err);
-        sendSetupSSE(setupId, 'error', { message: err.message });
+        sendSetupEvent(setupId, 'error', { message: err.message });
       } finally {
         activeSetups.delete(setupKey);
       }
@@ -252,43 +194,4 @@ router.post('/api/setup/local', async (req, res) => {
   }
 });
 
-// ---------------------------------------------------------------------------
-// GET /api/setup/local/:setupId/progress
-// ---------------------------------------------------------------------------
-
-/**
- * SSE endpoint for streaming local review setup progress to the client.
- */
-router.get('/api/setup/local/:setupId/progress', (req, res) => {
-  const { setupId } = req.params;
-
-  if (!setupId) {
-    return res.status(400).json({ error: 'Missing setupId parameter' });
-  }
-
-  // SSE headers
-  res.writeHead(200, {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection': 'keep-alive'
-  });
-
-  // Register this client
-  if (!setupProgressClients.has(setupId)) {
-    setupProgressClients.set(setupId, new Set());
-  }
-  setupProgressClients.get(setupId).add(res);
-
-  // Clean up on disconnect
-  req.on('close', () => {
-    const clients = setupProgressClients.get(setupId);
-    if (clients) {
-      clients.delete(res);
-      if (clients.size === 0) {
-        setupProgressClients.delete(setupId);
-      }
-    }
-  });
-});
-
 module.exports = router;

package/src/routes/shared.js

@@ -7,6 +7,7 @@
  */
 
 const logger = require('../utils/logger');
+const ws = require('../ws');
 
 /**
  * Custom error class for analysis cancellation
@@ -27,9 +28,6 @@ const activeAnalyses = new Map();
 // Unified map: replaces the previous separate prToAnalysisId and localReviewToAnalysisId maps.
 const reviewToAnalysisId = new Map();
 
-// Store SSE clients for real-time progress updates
-const progressClients = new Map();
-
 // Store local review diff data keyed by reviewId
 // Using a Map avoids process.env size limits and security concerns
 const localReviewDiffs = new Map();
@@ -42,10 +40,6 @@ const activeProcesses = new Map();
 // Maps setupKey (e.g., "pr:owner/repo/123" or "local:/path") -> { setupId, promise }
 const activeSetups = new Map();
 
-// Store SSE clients for setup progress updates
-// Maps setupId -> Set of response objects
-const setupProgressClients = new Map();
-
 /**
  * Get the model to use for AI analysis
  * Priority: CLI flag (PAIR_REVIEW_MODEL env var) > config.default_model > 'opus' default
@@ -115,33 +109,12 @@ function determineCompletionInfo(result) {
 }
 
 /**
- * Broadcast progress update to all connected SSE clients
+ * Broadcast progress update to all WebSocket clients subscribed to `analysis:{analysisId}`.
  * @param {string} analysisId - Analysis ID
  * @param {Object} progressData - Progress data to broadcast
  */
 function broadcastProgress(analysisId, progressData) {
-  const clients = progressClients.get(analysisId);
-  if (clients && clients.size > 0) {
-    const message = `data: ${JSON.stringify({
-      type: 'progress',
-      ...progressData
-    })}\n\n`;
-
-    // Send to all connected clients
-    clients.forEach(client => {
-      try {
-        client.write(message);
-      } catch (error) {
-        // Remove dead clients
-        clients.delete(client);
-      }
-    });
-
-    // Clean up if no clients left
-    if (clients.size === 0) {
-      progressClients.delete(analysisId);
-    }
-  }
+  ws.broadcast('analysis:' + analysisId, { type: 'progress', ...progressData });
 }
 
 /**
@@ -206,27 +179,12 @@ function isAnalysisCancelled(analysisId) {
 }
 
 /**
- * Broadcast setup progress to all connected SSE clients for a given setupId
+ * Broadcast setup progress to all WebSocket clients subscribed to `setup:{setupId}`.
  * @param {string} setupId - Setup operation ID
  * @param {Object} data - Progress data to broadcast
  */
 function broadcastSetupProgress(setupId, data) {
-  const clients = setupProgressClients.get(setupId);
-  if (clients && clients.size > 0) {
-    const message = `data: ${JSON.stringify(data)}\n\n`;
-
-    clients.forEach(client => {
-      try {
-        client.write(message);
-      } catch (error) {
-        clients.delete(client);
-      }
-    });
-
-    if (clients.size === 0) {
-      setupProgressClients.delete(setupId);
-    }
-  }
+  ws.broadcast('setup:' + setupId, data);
 }
 
 /**
@@ -426,11 +384,9 @@ module.exports = {
   CancellationError,
   activeAnalyses,
   reviewToAnalysisId,
-  progressClients,
   localReviewDiffs,
   activeProcesses,
   activeSetups,
-  setupProgressClients,
   getModel,
   determineCompletionInfo,
   broadcastProgress,

package/src/server.js

@@ -6,6 +6,7 @@ const { initializeDatabase, getDatabaseStatus, queryOne, run } = require('./data
 const { normalizeRepository } = require('./utils/paths');
 const { applyConfigOverrides, checkAllProviders } = require('./ai');
 const logger = require('./utils/logger');
+const { attachWebSocket, closeAll: closeAllWS } = require('./ws');
 
 let db = null;
 let server = null;
@@ -305,6 +306,7 @@ async function startServer(sharedDb = null) {
 
     server = app.listen(port, () => {
       console.log(`Server running on http://localhost:${port}`);
+      attachWebSocket(server);
     });
 
     server.on('error', (error) => {
@@ -343,6 +345,8 @@ async function gracefulShutdown(signal) {
     }
   }
 
+  closeAllWS();
+
   if (server) {
     server.close(() => {
       if (db) {

package/src/utils/comment-formatter.js

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/**
+ * Shared comment formatter for adopted AI suggestions.
+ * Provides configurable formatting with preset templates.
+ */
+
+const { getEmoji } = require('./category-emoji');
+
+/**
+ * Preset format templates for adopted comments.
+ * Template placeholders: {emoji}, {category}, {title}, {description}, {suggestion}
+ * Conditional sections: {?field}...{/field} — content is kept when field is truthy, stripped when falsy.
+ */
+const PRESETS = {
+  legacy: '{emoji} **{category}**: {description}{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}',
+  minimal: '[{category}] {description}{?suggestion}\n\n{suggestion}{/suggestion}',
+  plain: '{description}{?suggestion}\n\n{suggestion}{/suggestion}',
+  'emoji-only': '{emoji} {description}{?suggestion}\n\n{suggestion}{/suggestion}',
+  maximal: '{emoji} **{category}**{?title}: {title}{/title}\n\n{description}{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}'
+};
+
+/**
+ * Resolve a config value into a format configuration object.
+ * @param {string|Object|undefined} config - Preset name string, custom config object, or undefined
+ * @returns {{ template: string, emojiOverrides: Object, categoryOverrides: Object }}
+ */
+function resolveFormat(config) {
+  if (!config || typeof config === 'string') {
+    const presetName = config || 'legacy';
+    const template = PRESETS[presetName] || PRESETS.legacy;
+    return { template, emojiOverrides: {}, categoryOverrides: {} };
+  }
+
+  // Custom object config
+  return {
+    template: config.template || PRESETS.legacy,
+    emojiOverrides: config.emojiOverrides || {},
+    categoryOverrides: config.categoryOverrides || {}
+  };
+}
+
+/**
+ * Capitalize a hyphenated category name.
+ * e.g., 'code-style' -> 'Code Style', 'bug' -> 'Bug'
+ * @param {string} category
+ * @returns {string}
+ */
+function capitalizeCategory(category) {
+  return category
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Process conditional sections in a template.
+ * Syntax: {?fieldName}content{/fieldName}
+ * When the field value is truthy, the delimiters are stripped and content is kept.
+ * When the field value is falsy/empty/undefined, the entire block is removed.
+ *
+ * @param {string} template - Template with conditional sections
+ * @param {Object} values - Map of field names to their values
+ * @returns {string} Template with conditional sections resolved
+ */
+function processConditionalSections(template, values) {
+  return template.replace(/\{\?(\w+)\}([\s\S]*?)\{\/\1\}/g, (match, fieldName, content) => {
+    const value = values[fieldName];
+    if (value !== undefined && value !== null && value !== '') {
+      return content;
+    }
+    return '';
+  });
+}
+
+/**
+ * Format an adopted comment using the given format configuration.
+ * Handles legacy data where suggestion_text was concatenated into body.
+ *
+ * @param {{ body: string, suggestionText?: string, category?: string, title?: string }} fields
+ * @param {{ template: string, emojiOverrides: Object, categoryOverrides: Object }} formatConfig
+ * @returns {string} Formatted comment text
+ */
+function formatAdoptedComment(fields, formatConfig) {
+  const { body, title } = fields;
+  let { category, suggestionText } = fields;
+
+  if (!category) {
+    return body || '';
+  }
+
+  category = category.toLowerCase();
+
+  // Legacy handling: if no separate suggestionText, try to split from body
+  let description = body || '';
+  if (!suggestionText && description.includes('\n\n**Suggestion:** ')) {
+    const splitIndex = description.indexOf('\n\n**Suggestion:** ');
+    suggestionText = description.slice(splitIndex + '\n\n**Suggestion:** '.length);
+    description = description.slice(0, splitIndex);
+  }
+
+  const config = formatConfig || resolveFormat();
+
+  // Resolve emoji from original category BEFORE applying overrides,
+  // so overridden categories keep the original category's emoji
+  const emoji = config.emojiOverrides?.[category] || getEmoji(category);
+
+  // Apply category overrides (e.g., "bug" -> "defect")
+  if (config.categoryOverrides && config.categoryOverrides[category]) {
+    category = config.categoryOverrides[category];
+  }
+  const capitalizedCategory = capitalizeCategory(category);
+
+  // Process conditional sections first, then replace individual placeholders
+  const fieldValues = {
+    suggestion: suggestionText || '',
+    title: title || '',
+    emoji,
+    category: capitalizedCategory,
+    description
+  };
+
+  let result = processConditionalSections(config.template, fieldValues);
+
+  // Replace placeholders
+  result = result.replace(/\{emoji\}/g, emoji);
+  result = result.replace(/\{category\}/g, capitalizedCategory);
+  result = result.replace(/\{title\}/g, title || '');
+  result = result.replace(/\{description\}/g, description);
+  result = result.replace(/\{suggestion\}/g, suggestionText || '');
+
+  // Ensure code fences start on their own line
+  result = result.replace(/([^\n])(```)/g, '$1\n$2');
+
+  return result.trimEnd();
+}
+
+module.exports = { PRESETS, resolveFormat, formatAdoptedComment, capitalizeCategory, processConditionalSections };

package/src/ws/index.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+module.exports = require('./server');

package/src/ws/server.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+const { WebSocketServer } = require('ws');
+const logger = require('../utils/logger');
+
+const HEARTBEAT_INTERVAL = 30000;
+
+let wss = null;
+let heartbeatTimer = null;
+
+/**
+ * Attach a WebSocket server to an existing HTTP server.
+ * Operates in noServer mode, handling upgrade requests on the /ws path only.
+ * @param {import('http').Server} httpServer
+ */
+function attachWebSocket(httpServer) {
+  wss = new WebSocketServer({ noServer: true });
+
+  httpServer.on('upgrade', (request, socket, head) => {
+    const { pathname } = new URL(request.url, `http://${request.headers.host}`);
+    if (pathname !== '/ws') {
+      socket.destroy();
+      return;
+    }
+
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      wss.emit('connection', ws, request);
+    });
+  });
+
+  wss.on('connection', (ws) => {
+    ws._topics = new Set();
+    ws.isAlive = true;
+
+    ws.on('pong', () => {
+      ws.isAlive = true;
+    });
+
+    ws.on('message', (data) => {
+      let msg;
+      try {
+        msg = JSON.parse(data);
+      } catch {
+        logger.warn('WS: received non-JSON message');
+        return;
+      }
+
+      const { action, topic } = msg;
+      if (!topic) return;
+
+      if (action === 'subscribe') {
+        ws._topics.add(topic);
+      } else if (action === 'unsubscribe') {
+        ws._topics.delete(topic);
+      }
+    });
+
+    ws.on('close', () => {
+      ws._topics.clear();
+    });
+
+    ws.on('error', (err) => {
+      logger.warn(`WS: client error: ${err.message}`);
+      ws._topics.clear();
+    });
+  });
+
+  // Heartbeat: ping every HEARTBEAT_INTERVAL, terminate dead connections
+  heartbeatTimer = setInterval(() => {
+    wss.clients.forEach((ws) => {
+      if (!ws.isAlive) {
+        logger.debug('WS: terminating unresponsive client');
+        ws.terminate();
+        return;
+      }
+      ws.isAlive = false;
+      ws.ping();
+    });
+  }, HEARTBEAT_INTERVAL);
+
+  logger.info('WebSocket server attached on /ws');
+}
+
+/**
+ * Broadcast a payload to all clients subscribed to the given topic.
+ * @param {string} topic
+ * @param {object} payload
+ */
+function broadcast(topic, payload) {
+  if (!wss) return;
+
+  const message = JSON.stringify({ ...payload, topic });
+
+  wss.clients.forEach((ws) => {
+    if (ws.readyState === ws.OPEN && ws._topics && ws._topics.has(topic)) {
+      try {
+        ws.send(message);
+      } catch (err) {
+        logger.debug(`WS: failed to send to client: ${err.message}`);
+      }
+    }
+  });
+}
+
+/**
+ * Close all connections and shut down the WebSocket server.
+ */
+function closeAll() {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
+  if (!wss) return;
+
+  wss.clients.forEach((ws) => {
+    ws.terminate();
+  });
+
+  wss.close();
+  wss = null;
+}
+
+module.exports = { attachWebSocket, broadcast, closeAll, get _wss() { return wss; } };

package/src/sse/review-events.js

@@ -1,46 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
-/**
- * Shared SSE client registry and review-scoped event broadcaster.
- *
- * All SSE connections (chat, analysis, etc.) share a single Set of
- * Express response objects.  broadcastReviewEvent sends review-level
- * events (as opposed to session-level events handled in chat.js).
- */
-
-const logger = require('../utils/logger');
-
-/**
- * Connected SSE clients shared across all route modules.
- * Each entry is an Express response object with an open SSE connection.
- * @type {Set<import('express').Response>}
- */
-const sseClients = new Set();
-
-/**
- * Broadcast a review-scoped SSE event to all connected clients.
- * Optionally includes a `sourceClientId` so the originating browser tab
- * can recognise (and skip) its own echo.
- *
- * @param {number} reviewId - Review ID to include in the event
- * @param {Object} payload - Event data (must include at minimum a `type` field)
- * @param {Object} [options]
- * @param {string} [options.sourceClientId] - Client ID of the tab that triggered the mutation
- */
-function broadcastReviewEvent(reviewId, payload, options = {}) {
-  const envelope = { ...payload, reviewId };
-  if (options.sourceClientId) {
-    envelope.sourceClientId = options.sourceClientId;
-  }
-  const data = JSON.stringify(envelope);
-  for (const client of sseClients) {
-    try {
-      client.write(`data: ${data}\n\n`);
-    } catch {
-      // Client disconnected — remove from set
-      sseClients.delete(client);
-      logger.debug('[ReviewEvents] Removed disconnected SSE client');
-    }
-  }
-}
-
-module.exports = { sseClients, broadcastReviewEvent };