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

package/public/js/ws-client.js

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Browser-side WebSocket client singleton.
+ * Provides topic-based pub/sub over a single WebSocket connection
+ * with automatic reconnection and subscription restoration.
+ */
+(function () {
+  'use strict';
+
+  class WSClient {
+    constructor() {
+      /** @type {WebSocket|null} */
+      this._ws = null;
+      /** @type {Map<string, Set<Function>>} topic -> callbacks */
+      this._subscriptions = new Map();
+      /** @type {boolean} */
+      this.connected = false;
+      /** @type {number} current backoff delay in ms */
+      this._backoff = 1000;
+      /** @type {number} */
+      this._backoffMax = 10000;
+      /** @type {boolean} whether close() was called intentionally */
+      this._closed = false;
+      /** @type {number|null} reconnect timer id */
+      this._reconnectTimer = null;
+      /** @type {boolean} whether at least one connection has been established */
+      this._hasConnected = false;
+    }
+
+    /**
+     * Open the WebSocket connection. No-op if already connected or connecting.
+     */
+    connect() {
+      if (this._ws && (this._ws.readyState === WebSocket.OPEN || this._ws.readyState === WebSocket.CONNECTING)) {
+        return;
+      }
+      this._closed = false;
+      const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const url = `${protocol}//${location.host}/ws`;
+      this._ws = new WebSocket(url);
+
+      this._ws.onopen = () => {
+        this.connected = true;
+        this._backoff = 1000;
+        // Re-subscribe to all active topics (_subscriptions is authoritative)
+        for (const topic of this._subscriptions.keys()) {
+          this._ws.send(JSON.stringify({ action: 'subscribe', topic }));
+        }
+        // Emit reconnected event on subsequent opens (not the initial connect)
+        if (this._hasConnected) {
+          window.dispatchEvent(new CustomEvent('wsReconnected'));
+        }
+        this._hasConnected = true;
+      };
+
+      this._ws.onmessage = (event) => {
+        let msg;
+        try {
+          msg = JSON.parse(event.data);
+        } catch {
+          return;
+        }
+        const callbacks = this._subscriptions.get(msg.topic);
+        if (callbacks) {
+          for (const cb of [...callbacks]) {
+            try {
+              cb(msg);
+            } catch (e) {
+              console.error('[WSClient] Subscriber error:', e);
+            }
+          }
+        }
+      };
+
+      this._ws.onclose = () => {
+        this.connected = false;
+        this._ws = null;
+        if (!this._closed) {
+          this._scheduleReconnect();
+        }
+      };
+
+      this._ws.onerror = () => {
+        // onclose will fire after onerror, which handles reconnection
+      };
+    }
+
+    /**
+     * Subscribe to a topic. Returns an unsubscribe function.
+     * Safe to call before connect() — the subscribe message will be
+     * sent once the connection is established.
+     *
+     * @param {string} topic
+     * @param {Function} callback - receives the full parsed message object
+     * @returns {Function} unsubscribe
+     */
+    subscribe(topic, callback) {
+      let callbacks = this._subscriptions.get(topic);
+      if (!callbacks) {
+        callbacks = new Set();
+        this._subscriptions.set(topic, callbacks);
+      }
+      callbacks.add(callback);
+
+      // Send subscribe message if connected (otherwise it will be sent on connect via _subscriptions)
+      if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+        this._ws.send(JSON.stringify({ action: 'subscribe', topic }));
+      }
+
+      // Return unsubscribe function
+      return () => {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this._subscriptions.delete(topic);
+          const unsub = { action: 'unsubscribe', topic };
+          if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+            this._ws.send(JSON.stringify(unsub));
+          }
+        }
+      };
+    }
+
+    /**
+     * Close the WebSocket and stop reconnection.
+     */
+    close() {
+      this._closed = true;
+      if (this._reconnectTimer !== null) {
+        clearTimeout(this._reconnectTimer);
+        this._reconnectTimer = null;
+      }
+      if (this._ws) {
+        this._ws.close();
+        this._ws = null;
+      }
+      this.connected = false;
+    }
+
+    /** @private */
+    _scheduleReconnect() {
+      this._reconnectTimer = setTimeout(() => {
+        this._reconnectTimer = null;
+        this.connect();
+      }, this._backoff);
+      this._backoff = Math.min(this._backoff * 2, this._backoffMax);
+    }
+  }
+
+  // Export as singleton on window
+  if (typeof window !== 'undefined') {
+    window.WSClient = WSClient;
+    window.wsClient = new WSClient();
+  }
+})();

package/public/local.html

@@ -516,6 +516,9 @@
     <!-- Timestamp parsing utility -->
     <script src="/js/utils/time.js"></script>
 
+    <!-- WebSocket client -->
+    <script src="/js/ws-client.js"></script>
+
     <!-- Components -->
     <script src="/js/components/Toast.js"></script>
     <script src="/js/components/ConfirmDialog.js"></script>

package/public/pr.html

@@ -339,6 +339,9 @@
     <!-- Timestamp parsing utility -->
     <script src="/js/utils/time.js"></script>
 
+    <!-- WebSocket client -->
+    <script src="/js/ws-client.js"></script>
+
     <!-- Components -->
     <script src="/js/components/Toast.js"></script>
     <script src="/js/components/ConfirmDialog.js"></script>

package/public/setup.html

@@ -517,6 +517,9 @@
         </div>
     </div>
 
+    <!-- WebSocket client -->
+    <script src="/js/ws-client.js"></script>
+
     <script>
         // SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -718,17 +721,15 @@
 
             /* ── Setup Flow ── */
             async function startSetup() {
-                var postUrl, sseBaseUrl;
+                var postUrl;
 
                 if (mode === 'pr') {
                     var o = encodeURIComponent(context.owner);
                     var r = encodeURIComponent(context.repo);
                     var n = encodeURIComponent(context.number);
                     postUrl = '/api/setup/pr/' + o + '/' + r + '/' + n;
-                    sseBaseUrl = postUrl + '/progress';
                 } else if (mode === 'local') {
                     postUrl = '/api/setup/local';
-                    sseBaseUrl = '/api/setup/local';
                 } else {
                     showError('Unable to determine review mode. Please return home and try again.');
                     return;
@@ -765,15 +766,7 @@
                         throw new Error('No setup ID returned from server');
                     }
 
-                    // Connect to SSE endpoint
-                    var sseUrl;
-                    if (mode === 'pr') {
-                        sseUrl = sseBaseUrl + '?setupId=' + encodeURIComponent(data.setupId);
-                    } else {
-                        sseUrl = sseBaseUrl + '/' + encodeURIComponent(data.setupId) + '/progress';
-                    }
-
-                    connectSSE(sseUrl);
+                    connectWS(data.setupId);
 
                 } catch (err) {
                     showError(err.message || 'Failed to start setup. Please try again.');
@@ -784,98 +777,66 @@
                 }
             }
 
-            /* ── SSE Connection ── */
-            function connectSSE(url) {
-                var eventSource = new EventSource(url);
-
-                eventSource.addEventListener('step', function(e) {
-                    try {
-                        var payload = JSON.parse(e.data);
-                        var stepId = payload.step || payload.id;
-                        var status = payload.status || 'running';
-                        var message = payload.message || '';
-
-                        stepStates[stepId] = { status: status, message: message };
-                        renderSteps();
-                        updateProgressBar();
-                    } catch (err) {
-                        console.error('Error parsing step event:', err);
-                    }
-                });
-
-                eventSource.addEventListener('complete', function(e) {
-                    try {
-                        var payload = JSON.parse(e.data);
+            /* ── WebSocket Connection ── */
+            // Note: No wsReconnected recovery here. Setup is a short-lived,
+            // one-time flow — if the WS drops mid-setup, the user can simply
+            // reload the page. Not worth the complexity of state recovery.
+            function connectWS(setupId) {
+                window.wsClient.connect();
+
+                var unsub = window.wsClient.subscribe('setup:' + setupId, function(msg) {
+                    switch (msg.type) {
+                        case 'step': {
+                            var stepId = msg.step || msg.id;
+                            var status = msg.status || 'running';
+                            var message = msg.message || '';
+
+                            stepStates[stepId] = { status: status, message: message };
+                            renderSteps();
+                            updateProgressBar();
+                            break;
+                        }
 
-                        // Mark all steps as completed
-                        for (var i = 0; i < steps.length; i++) {
-                            if (!stepStates[steps[i].id] || stepStates[steps[i].id].status !== 'completed') {
-                                stepStates[steps[i].id] = { status: 'completed', message: '' };
+                        case 'complete': {
+                            unsub();
+                            // Mark all steps as completed
+                            for (var i = 0; i < steps.length; i++) {
+                                if (!stepStates[steps[i].id] || stepStates[steps[i].id].status !== 'completed') {
+                                    stepStates[steps[i].id] = { status: 'completed', message: '' };
+                                }
                             }
+                            renderSteps();
+                            updateProgressBar();
+                            showRedirect();
+
+                            // Small delay so the user sees the completed state
+                            setTimeout(function() {
+                                if (msg.reviewUrl) {
+                                    var targetUrl = new URL(msg.reviewUrl, window.location.origin);
+                                    var qs = new URLSearchParams(window.location.search);
+                                    if (qs.get('analyze') === 'true') targetUrl.searchParams.set('analyze', qs.get('analyze'));
+                                    window.location.href = targetUrl.toString();
+                                }
+                            }, 400);
+                            break;
                         }
-                        renderSteps();
-                        updateProgressBar();
-
-                        showRedirect();
-                        eventSource.close();
-
-                        // Small delay so the user sees the completed state
-                        setTimeout(function() {
-                            if (payload.reviewUrl) {
-                                var targetUrl = new URL(payload.reviewUrl, window.location.origin);
-                                var qs = new URLSearchParams(window.location.search);
-                                if (qs.get('analyze') === 'true') targetUrl.searchParams.set('analyze', qs.get('analyze'));
-                                window.location.href = targetUrl.toString();
-                            }
-                        }, 400);
-                    } catch (err) {
-                        console.error('Error parsing complete event:', err);
-                    }
-                });
 
-                eventSource.addEventListener('error', function(e) {
-                    // SSE 'error' event type from server (custom)
-                    if (e.data) {
-                        try {
-                            var payload = JSON.parse(e.data);
-                            var failedStep = payload.step;
-                            var errorMsg = payload.message || 'An unexpected error occurred';
+                        case 'error': {
+                            unsub();
+                            var failedStep = msg.step;
+                            var errorMsg = msg.message || 'An unexpected error occurred';
 
-                            if (failedStep && stepStates[failedStep]) {
-                                stepStates[failedStep] = { status: 'error', message: errorMsg };
-                            } else if (failedStep) {
+                            if (failedStep) {
                                 stepStates[failedStep] = { status: 'error', message: errorMsg };
                             }
 
                             renderSteps();
                             updateProgressBar();
                             showError(errorMsg);
-                            eventSource.close();
-                            return;
-                        } catch (parseErr) {
-                            // Not a JSON error event, fall through
-                        }
-                    }
-
-                    // Native EventSource error (connection lost, etc.)
-                    if (eventSource.readyState === EventSource.CLOSED) {
-                        // Check if we got any errors already shown
-                        if (!errorSection.classList.contains('visible')) {
-                            showError('Connection to server was lost. Please retry.');
-                            updateProgressBar();
+                            break;
                         }
                     }
                 });
-
-                eventSource.onerror = function() {
-                    // EventSource connection failure
-                    if (eventSource.readyState === EventSource.CLOSED) {
-                        if (!errorSection.classList.contains('visible') && !redirectSection.classList.contains('visible')) {
-                            showError('Connection to server was lost. Please retry.');
-                            updateProgressBar();
-                        }
-                    }
-                };
             }
 
             /* ── Kick Off ── */

package/src/ai/analyzer.js

@@ -3505,12 +3505,8 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         continue;
       }
 
-      const suggestionText = suggestion.suggestion;
-      const hasSuggestionBlock = suggestionText?.trimStart().startsWith('```suggestion');
-      const body = suggestion.description +
-        (suggestionText
-          ? (hasSuggestionBlock ? '\n\n' + suggestionText : '\n\n**Suggestion:** ' + suggestionText)
-          : '');
+      const body = suggestion.description;
+      const suggestionText = suggestion.suggestion || null;
 
       const isFileLevel = suggestion.is_file_level === true || suggestion.line_start === null ? 1 : 0;
       const side = suggestion.old_or_new === 'OLD' ? 'LEFT' : 'RIGHT';
@@ -3518,9 +3514,9 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       await dbRun(this.db, `
         INSERT INTO comments (
           review_id, source, author, ai_run_id, ai_level, ai_confidence,
-          file, line_start, line_end, side, type, title, body, reasoning, status, is_file_level,
+          file, line_start, line_end, side, type, title, body, suggestion_text, reasoning, status, is_file_level,
           voice_id, is_raw
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `, [
         reviewId,
         'ai',
@@ -3535,6 +3531,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         suggestion.type,
         suggestion.title,
         body,
+        suggestionText,
         suggestion.reasoning ? JSON.stringify(suggestion.reasoning) : null,
         'active',
         isFileLevel,

package/src/config.js

@@ -7,6 +7,7 @@ const logger = require('./utils/logger');
 const CONFIG_DIR = path.join(os.homedir(), '.pair-review');
 const DEFAULT_CHECKOUT_TIMEOUT_MS = 300000;
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const CONFIG_LOCAL_FILE = path.join(CONFIG_DIR, 'config.local.json');
 const CONFIG_EXAMPLE_FILE = path.join(CONFIG_DIR, 'config.example.json');
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
@@ -22,6 +23,7 @@ const DEFAULT_CONFIG = {
   db_name: "",  // Custom database filename (default: database.db). Useful for per-worktree isolation.
   yolo: false,  // When true, skips fine-grained AI provider permission setup (equivalent to --yolo CLI flag)
   enable_chat: true,  // When true, enables the chat panel feature (requires Pi AI provider)
+  comment_format: "legacy",  // Comment format preset or custom template for adopted suggestions
   chat: { enable_shortcuts: true },  // Chat panel settings (enable_shortcuts: show action shortcut buttons)
   providers: {},  // Custom provider configurations (overrides built-in defaults)
   monorepos: {},  // Monorepo configurations: { "owner/repo": { path: "~/path/to/clone" } }
@@ -37,6 +39,36 @@ function validatePort(port) {
   return Number.isInteger(port) && port >= 1024 && port <= 65535;
 }
 
+/**
+ * Recursively merges source into target for plain objects.
+ * Arrays and scalars in source replace the corresponding value in target.
+ * Null in source overwrites target. Returns a new object; inputs are not mutated.
+ * @param {Object} target - Base object
+ * @param {Object} source - Object to merge on top
+ * @returns {Object} - Merged result
+ */
+function deepMerge(target, source) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return target;
+  if (!target || typeof target !== 'object' || Array.isArray(target)) return { ...source };
+
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+    if (
+      srcVal !== null &&
+      typeof srcVal === 'object' && !Array.isArray(srcVal) &&
+      tgtVal !== null &&
+      typeof tgtVal === 'object' && !Array.isArray(tgtVal)
+    ) {
+      result[key] = deepMerge(tgtVal, srcVal);
+    } else {
+      result[key] = srcVal;
+    }
+  }
+  return result;
+}
+
 /**
  * Gets a config value with fallback to legacy key names
  * Supports backwards compatibility without modifying the config file
@@ -135,63 +167,51 @@ async function ensureConfigDir() {
 async function loadConfig() {
   await ensureConfigDir();
 
-  try {
-    const configData = await fs.readFile(CONFIG_FILE, 'utf8');
-    const config = JSON.parse(configData);
-
-    // Merge with defaults to ensure all keys exist
-    // Legacy keys ('provider', 'model') are handled lazily via getDefaultProvider/getDefaultModel
-    const mergedConfig = { ...DEFAULT_CONFIG, ...config };
-    // Deep-merge one level for object-valued defaults (e.g. chat, providers, monorepos)
-    for (const key of Object.keys(DEFAULT_CONFIG)) {
-      if (typeof DEFAULT_CONFIG[key] === 'object' && DEFAULT_CONFIG[key] !== null && !Array.isArray(DEFAULT_CONFIG[key])) {
-        mergedConfig[key] = { ...DEFAULT_CONFIG[key], ...config[key] };
-      }
-    }
+  const localDir = path.join(process.cwd(), '.pair-review');
+  const sources = [
+    { path: CONFIG_FILE,                                label: 'global config',        required: true  },
+    { path: CONFIG_LOCAL_FILE,                           label: 'global local config',  required: false },
+    { path: path.join(localDir, 'config.json'),         label: 'project config',       required: false },
+    { path: path.join(localDir, 'config.local.json'),   label: 'project local config', required: false },
+  ];
+
+  let mergedConfig = { ...DEFAULT_CONFIG };
+  let isFirstRun = false;
 
-    // Merge local config (CWD/.pair-review/config.json) on top of global config
+  for (const source of sources) {
     try {
-      const localConfigPath = path.join(process.cwd(), '.pair-review', 'config.json');
-      const localConfigData = await fs.readFile(localConfigPath, 'utf8');
-      const localConfig = JSON.parse(localConfigData);
-      Object.assign(mergedConfig, localConfig);
-      // Deep-merge one level for object-valued local config overrides
-      for (const key of Object.keys(DEFAULT_CONFIG)) {
-        if (typeof DEFAULT_CONFIG[key] === 'object' && DEFAULT_CONFIG[key] !== null && !Array.isArray(DEFAULT_CONFIG[key])) {
-          mergedConfig[key] = { ...DEFAULT_CONFIG[key], ...config[key], ...localConfig[key] };
+      const data = await fs.readFile(source.path, 'utf8');
+      const parsed = JSON.parse(data);
+      mergedConfig = deepMerge(mergedConfig, parsed);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        if (source.required) {
+          // Global config doesn't exist — create it with defaults
+          const config = { ...DEFAULT_CONFIG };
+          await saveConfig(config);
+          logger.debug(`Created default config file: ${CONFIG_FILE}`);
+          isFirstRun = true;
         }
-      }
-    } catch (localError) {
-      if (localError.code !== 'ENOENT') {
-        if (localError instanceof SyntaxError) {
-          logger.warn('Malformed local config at .pair-review/config.json, skipping');
-        } else {
-          throw localError;
+        // Optional files: skip silently
+      } else if (error instanceof SyntaxError) {
+        if (source.required) {
+          console.error(`Invalid configuration file at ~/.pair-review/config.json`);
+          process.exit(1);
         }
+        logger.warn(`Malformed config at ${source.label}, skipping`);
+      } else {
+        throw error;
       }
     }
+  }
 
-    // Validate port
-    if (!validatePort(mergedConfig.port)) {
-      console.error(`Invalid port number ${mergedConfig.port}`);
-      process.exit(1);
-    }
-
-    return { config: mergedConfig, isFirstRun: false };
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      // Config file doesn't exist, create it with defaults
-      const config = { ...DEFAULT_CONFIG };
-      await saveConfig(config);
-      logger.debug(`Created default config file: ${CONFIG_FILE}`);
-      return { config, isFirstRun: true };
-    } else if (error instanceof SyntaxError) {
-      console.error(`Invalid configuration file at ~/.pair-review/config.json`);
-      process.exit(1);
-    } else {
-      throw error;
-    }
+  // Validate port
+  if (!validatePort(mergedConfig.port)) {
+    console.error(`Invalid port number ${mergedConfig.port}`);
+    process.exit(1);
   }
+
+  return { config: mergedConfig, isFirstRun };
 }
 
 /**
@@ -424,6 +444,7 @@ function warnIfDevModeWithoutDbName(config) {
 }
 
 module.exports = {
+  deepMerge,
   loadConfig,
   saveConfig,
   getConfigDir,

package/src/database.js

@@ -20,7 +20,7 @@ function getDbPath() {
 /**
  * Current schema version - increment this when adding new migrations
  */
-const CURRENT_SCHEMA_VERSION = 24;
+const CURRENT_SCHEMA_VERSION = 25;
 
 /**
  * Database schema SQL statements
@@ -80,6 +80,7 @@ const SCHEMA_SQL = {
       type TEXT,
       title TEXT,
       body TEXT,
+      suggestion_text TEXT,
       reasoning TEXT,
 
       status TEXT DEFAULT 'active' CHECK(status IN ('active', 'dismissed', 'adopted', 'submitted', 'draft', 'inactive')),
@@ -1135,6 +1136,28 @@ const MIGRATIONS = {
     }
 
     console.log('Migration to schema version 24 complete');
+  },
+
+  // Migration to version 25: adds suggestion_text column to comments for structured suggestion storage
+  25: (db) => {
+    console.log('Migrating to schema version 25: Add suggestion_text column to comments');
+
+    const columns = db.prepare('PRAGMA table_info(comments)').all();
+    if (!columns.some(c => c.name === 'suggestion_text')) {
+      try {
+        db.prepare('ALTER TABLE comments ADD COLUMN suggestion_text TEXT').run();
+        console.log('  Added suggestion_text column to comments');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) {
+          throw error;
+        }
+        console.log('  Column suggestion_text already exists (race condition)');
+      }
+    } else {
+      console.log('  Column suggestion_text already exists');
+    }
+
+    console.log('Migration to schema version 25 complete');
   }
 };
 
@@ -2193,12 +2216,8 @@ class CommentRepository {
     }
 
     for (const suggestion of normalized) {
-      const suggestionText = suggestion.suggestion;
-      const hasSuggestionBlock = suggestionText?.trimStart().startsWith('```suggestion');
-      const body = suggestion.description +
-        (suggestionText
-          ? (hasSuggestionBlock ? '\n\n' + suggestionText : '\n\n**Suggestion:** ' + suggestionText)
-          : '');
+      const body = suggestion.description;
+      const suggestionText = suggestion.suggestion || null;
 
       // File-level suggestions have is_file_level=true or have null line_start
       const isFileLevel = suggestion.is_file_level === true || suggestion.line_start === null ? 1 : 0;
@@ -2209,8 +2228,8 @@ class CommentRepository {
       await run(this.db, `
         INSERT INTO comments (
           review_id, source, author, ai_run_id, ai_level, ai_confidence,
-          file, line_start, line_end, side, type, title, body, reasoning, status, is_file_level
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          file, line_start, line_end, side, type, title, body, suggestion_text, reasoning, status, is_file_level
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `, [
         reviewId,
         'ai',
@@ -2225,6 +2244,7 @@ class CommentRepository {
         suggestion.type,
         suggestion.title,
         body,
+        suggestionText,
         suggestion.reasoning ? JSON.stringify(suggestion.reasoning) : null,
         'active',
         isFileLevel