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

package/README.md

@@ -31,6 +31,7 @@
   - [Customization](#customization)
   - [Review Feedback Export](#review-feedback-export)
   - [Inline Comments](#inline-comments)
+  - [Comment Format](#comment-format)
   - [Local Mode](#local-mode)
 - [Claude Code Plugins](#claude-code-plugins)
 - [MCP Integration](#mcp-integration)
@@ -235,6 +236,22 @@ On first run, pair-review creates `~/.pair-review/config.example.json` with comp
 
 For advanced configuration with custom providers and models, see [AI Provider Configuration](#ai-provider-configuration) below.
 
+### Configuration Files
+
+pair-review loads configuration from multiple files, merged in order of increasing precedence:
+
+| Priority | File | Purpose |
+|----------|------|---------|
+| 1 (lowest) | Built-in defaults | Sensible defaults for all settings |
+| 2 | `~/.pair-review/config.json` | Global user configuration |
+| 3 | `~/.pair-review/config.local.json` | Personal overrides (gitignored) |
+| 4 | `.pair-review/config.json` | Project-specific configuration (can be checked in) |
+| 5 (highest) | `.pair-review/config.local.json` | Personal project overrides (gitignored) |
+
+Nested objects (like `chat`, `providers`, `monorepos`) are deep-merged across layers — you only need to specify the keys you want to override.
+
+**`config.local.json`** files are intended for personal overrides that should not be committed to version control. Add `config.local.json` to your `.gitignore`.
+
 ### Environment Variables
 
 pair-review supports several environment variables for customizing behavior:
@@ -484,6 +501,66 @@ The markdown includes file paths, line numbers, and your comments - everything t
 - Edit or discard AI suggestions before finalizing
 - Comments include file and line number for precision
 
+### Comment Format
+
+When AI suggestions are adopted as review comments, pair-review formats them with an emoji and category prefix by default. You can customize this format via the `comment_format` setting in `~/.pair-review/config.json`.
+
+**Presets:**
+
+| Preset | Template | Example Output (without suggestion)|
+|--------|----------|---------------|
+| `legacy` | `{emoji} **{category}**: {description}{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}` | 🐛 **Bug**: Missing null check |
+| `minimal` | `[{category}] {description}{?suggestion}\n\n{suggestion}{/suggestion}` | [Bug] Missing null check |
+| `plain` | `{description}{?suggestion}\n\n{suggestion}{/suggestion}` | Missing null check |
+| `emoji-only` | `{emoji} {description}{?suggestion}\n\n{suggestion}{/suggestion}` | 🐛 Missing null check |
+| `maximal` | `{emoji} **{category}**{?title}: {title}{/title}\n\n{description}{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}` | 🐛 **Bug**: Null Safety Issue (includes title) |
+
+To use a preset:
+
+```json
+{
+  "comment_format": "minimal"
+}
+```
+
+**Custom templates:**
+
+You can provide a custom template using these placeholders: `{emoji}`, `{category}`, `{title}`, `{description}`, `{suggestion}`.
+
+**Conditional sections:** Use `{?field}...{/field}` to conditionally include content. When the field value is truthy, the delimiters are stripped and the content is kept. When the field is empty/null/undefined, the entire block (including surrounding text within the delimiters) is removed. For example, `{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}` will omit the entire suggestion line when there is no remediation text.
+
+```json
+{
+  "comment_format": {
+    "template": "{emoji} **{category}**: {description}{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}",
+    "emojiOverrides": {
+      "bug": "🔴"
+    }
+  }
+}
+```
+
+**Category overrides:**
+
+Use `categoryOverrides` to rename categories in the formatted output. This is a string-to-string mapping where keys are the original category names (lowercase) and values are the replacement names.
+
+```json
+{
+  "comment_format": {
+    "template": "{emoji} **{category}**: {description}{?suggestion}\n\n**Suggestion:** {suggestion}{/suggestion}",
+    "categoryOverrides": { "bug": "defect", "performance": "perf" }
+  }
+}
+```
+
+- `{title}` uses the suggestion's title field if available.
+- `emojiOverrides` lets you replace the default emoji for specific categories.
+- `categoryOverrides` lets you rename categories (e.g., "bug" to "defect").
+
+Templates typically include `{description}` to render the suggestion body.
+
+**Builtin categories:** bug, improvement, praise, suggestion, design, performance, security, code-style
+
 ### Local Mode
 
 Review **unstaged**, uncommitted changes before creating a PR:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {
@@ -67,7 +67,8 @@
     "open": "^9.1.0",
     "simple-git": "^3.19.1",
     "update-notifier": "^5.1.0",
-    "uuid": "^11.1.0"
+    "uuid": "^11.1.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",

package/public/js/components/ChatPanel.js

@@ -18,8 +18,8 @@ class ChatPanel {
     this.reviewId = null;
     this.isOpen = false;
     this.isStreaming = false;
-    this.eventSource = null;
-    this._sseReconnectTimer = null;
+    this._chatUnsub = null;
+    this._reviewUnsub = null;
     this.messages = [];
     this._streamingContent = '';
     this._pendingContext = [];
@@ -28,7 +28,7 @@ class ChatPanel {
     this._contextItemId = null;   // suggestion ID or comment ID from context
     this._contextLineMeta = null;  // { file, line_start, line_end } — set when opened with line context
     this._pendingActionContext = null;  // { type, itemId } — set by action button handlers, consumed by sendMessage
-    this._resizeConfig = { min: 300, default: 400, storageKey: 'chat-panel-width' };
+    this._resizeConfig = ChatPanel.RESIZE_CONFIG;
     this._analysisContextRemoved = false;
     this._sessionAnalysisRunId = null; // tracks which AI run ID's context is loaded in the current session
     this._openPromise = null; // concurrency guard for open()
@@ -434,8 +434,8 @@ class ChatPanel {
     this.panel.classList.remove('chat-panel--closed');
     this.panel.classList.add('chat-panel--open');
 
-    // Ensure SSE is connected (but don't create a session yet — lazy creation)
-    this._ensureGlobalSSE();
+    // Ensure WebSocket subscriptions are active (but don't create a session yet — lazy creation)
+    this._ensureSubscriptions();
 
     // Load MRU session with message history (if any previous sessions exist).
     // Skip when opening with explicit context (suggestion/comment/file) — the
@@ -495,7 +495,7 @@ class ChatPanel {
   close() {
     this._hideSessionDropdown();
     // Reset UI streaming state (buttons) but keep isStreaming and _streamingContent
-    // intact so the background SSE handler can continue accumulating events.
+    // intact so the background WebSocket handler can continue accumulating events.
     this.sendBtn.style.display = '';
     this.stopBtn.style.display = 'none';
     this.sendBtn.disabled = !this.inputEl?.value?.trim();
@@ -544,6 +544,7 @@ class ChatPanel {
     // 2. Clear everything as normal
     this._finalizeStreaming();
     this.currentSessionId = null;
+    this._resubscribeChat(); // Unsubscribe old chat topic
     this.messages = [];
     this._streamingContent = '';
     this._pendingContext = [];
@@ -556,7 +557,6 @@ class ChatPanel {
     this._clearMessages();
     this._updateActionButtons();
     this._updateTitle(); // Reset title for new conversation
-    // SSE stays connected — it's multiplexed and will filter by sessionId
 
     // 3. Re-add analysis context (appears first, handled separately from pending arrays)
     this._ensureAnalysisContext();
@@ -626,6 +626,7 @@ class ChatPanel {
 
       const mru = sessions[0];
       this.currentSessionId = mru.id;
+      this._resubscribeChat();
       console.debug('[ChatPanel] Loaded MRU session:', mru.id, 'messages:', mru.message_count);
 
       if (mru.provider) {
@@ -786,6 +787,7 @@ class ChatPanel {
 
     // 2. Reset state
     this.currentSessionId = sessionId;
+    this._resubscribeChat();
     this.messages = [];
     this._streamingContent = '';
     this._pendingContext = [];
@@ -869,12 +871,12 @@ class ChatPanel {
   }
 
   /**
-   * Ensure the global SSE connection is active.
+   * Ensure WebSocket subscriptions are established for review and chat topics.
    * No longer creates sessions — that happens lazily on first message.
    * @returns {{sessionData: null}}
    */
   _ensureConnected() {
-    this._ensureGlobalSSE();
+    this._ensureSubscriptions();
     return { sessionData: null };
   }
 
@@ -893,6 +895,12 @@ class ChatPanel {
     this.reviewId = reviewId;
     console.debug('[ChatPanel] Late-bound reviewId:', reviewId);
 
+    // Subscribe to review topic now that reviewId is available.
+    // _ensureSubscriptions() skips this when reviewId is null at panel open time,
+    // so we must subscribe here. The chat subscription is a benign no-op when
+    // currentSessionId is null.
+    this._ensureSubscriptions();
+
     // Re-enable input now that reviewId is available
     if (this.inputEl.disabled) {
       this._enableInput();
@@ -942,6 +950,7 @@ class ChatPanel {
 
       const result = await response.json();
       this.currentSessionId = result.data.id;
+      this._resubscribeChat();
       console.debug('[ChatPanel] Session created:', this.currentSessionId);
       return result.data;
     } catch (error) {
@@ -975,7 +984,7 @@ class ChatPanel {
 
     // Lazy session creation: create on first message, not on panel open
     if (!this.currentSessionId) {
-      this._ensureGlobalSSE();
+      this._ensureSubscriptions();
       const sessionData = await this.createSession();
       if (!sessionData) {
         // Restore the user's message text into the input
@@ -1044,7 +1053,8 @@ class ChatPanel {
       if (response.status === 410) {
         console.debug('[ChatPanel] Session not resumable (410), creating new session and retrying');
         this.currentSessionId = null;
-        this._ensureGlobalSSE();
+        this._resubscribeChat();
+        this._ensureSubscriptions();
         const sessionData = await this.createSession();
         if (!sessionData) {
           throw new Error('Failed to create replacement session');
@@ -1061,7 +1071,7 @@ class ChatPanel {
         const err = await response.json().catch(() => ({}));
         throw new Error(err.error || 'Failed to send message');
       }
-      console.debug('[ChatPanel] Message accepted, waiting for SSE events');
+      console.debug('[ChatPanel] Message accepted, waiting for WebSocket events');
     } catch (error) {
       // Restore pending context so it's not lost
       this._pendingContext = savedContext;
@@ -1914,122 +1924,173 @@ class ChatPanel {
   }
 
   /**
-   * Ensure the global multiplexed SSE connection is established.
-   * Creates the EventSource once; subsequent calls are no-ops if already connected.
-   * Events are filtered by sessionId to dispatch only to the active session.
+   * Ensure WebSocket subscriptions are established for review and chat topics.
+   * Subscribes to review events (stable for page lifetime) and chat events
+   * (changes when session changes). Subsequent calls are no-ops if already subscribed.
    */
-  _ensureGlobalSSE() {
-    // Already connected or connecting — nothing to do
-    if (this.eventSource &&
-        this.eventSource.readyState !== EventSource.CLOSED) {
-      return;
+  _ensureSubscriptions() {
+    window.wsClient.connect();
+
+    // Subscribe to review events (stable for page lifetime)
+    if (this.reviewId && !this._reviewUnsub) {
+      this._reviewUnsub = window.wsClient.subscribe('review:' + this.reviewId, (msg) => {
+        if (msg.type?.startsWith('review:')) {
+          document.dispatchEvent(new CustomEvent(msg.type, {
+            detail: { ...msg }
+          }));
+        }
+      });
     }
 
-    // Clear any pending reconnect timer
-    clearTimeout(this._sseReconnectTimer);
-    this._sseReconnectTimer = null;
+    // Subscribe to chat session
+    if (this.currentSessionId && !this._chatUnsub) {
+      this._chatUnsub = window.wsClient.subscribe('chat:' + this.currentSessionId, (msg) => {
+        this._handleChatMessage(msg);
+      });
+    }
 
-    const url = '/api/chat/stream';
-    console.debug('[ChatPanel] Connecting multiplexed SSE:', url);
-    this.eventSource = new EventSource(url);
+    // Listen for WebSocket reconnects — any deltas broadcast during the
+    // reconnect gap are lost, so we re-fetch via HTTP to recover the stream.
+    if (!this._onReconnect) {
+      this._onReconnect = () => { this._recoverAfterReconnect(); };
+      window.addEventListener('wsReconnected', this._onReconnect);
+    }
+  }
 
-    this.eventSource.onmessage = (event) => {
-      try {
-        const data = JSON.parse(event.data);
+  /**
+   * Recover streaming state after a WebSocket reconnect.
+   * If a stream was in progress when the connection dropped, deltas broadcast
+   * during the gap are lost. Re-fetch the full message history via HTTP and
+   * replace the partial `_streamingContent` with the complete last assistant
+   * message. When not streaming, no action is needed.
+   */
+  async _recoverAfterReconnect() {
+    if (!this.isStreaming || !this.currentSessionId) return;
 
-        // Initial connection acknowledgement — no sessionId, just log
-        if (data.type === 'connected' && !data.sessionId) {
-          console.debug('[ChatPanel] Multiplexed SSE connected');
-          return;
+    try {
+      const response = await fetch(`/api/chat/session/${this.currentSessionId}/messages`);
+      if (!response.ok) return;
+
+      const result = await response.json();
+      const messages = result.data?.messages || [];
+
+      // Find the last assistant message — this is the one being streamed
+      let lastAssistant = null;
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].type === 'message' && messages[i].role === 'assistant') {
+          lastAssistant = messages[i];
+          break;
         }
+      }
 
-        // Route review-scoped events to document as CustomEvents
-        if (data.reviewId && data.type?.startsWith('review:')) {
-          document.dispatchEvent(new CustomEvent(data.type, {
-            detail: { ...data }
-          }));
-          return;
+      if (lastAssistant && lastAssistant.content) {
+        this._streamingContent = lastAssistant.content;
+        // The message is already persisted in the DB, so the stream is
+        // definitively complete. Finalize rather than continuing the
+        // streaming UI (which would leave the Stop button visible, etc.).
+        if (this.isOpen) {
+          this.finalizeStreamingMessage(lastAssistant.id);
+        } else {
+          this.messages.push({ role: 'assistant', content: lastAssistant.content, id: lastAssistant.id });
+          this._finalizeStreaming();
         }
+      }
+    } catch (err) {
+      console.warn('[ChatPanel] Failed to recover stream after reconnect:', err);
+    }
+  }
 
-        // Filter: only process events for the active session
-        if (data.sessionId !== this.currentSessionId) return;
+  /**
+   * Unsubscribe from the current chat topic and re-subscribe to the new one.
+   * Called whenever `this.currentSessionId` changes.
+   */
+  _resubscribeChat() {
+    if (this._chatUnsub) { this._chatUnsub(); this._chatUnsub = null; }
+    if (this.currentSessionId) {
+      this._chatUnsub = window.wsClient.subscribe('chat:' + this.currentSessionId, (msg) => {
+        this._handleChatMessage(msg);
+      });
+    }
+  }
 
-        if (data.type !== 'delta') {
-          console.debug('[ChatPanel] SSE event:', data.type, 'session:', data.sessionId);
-        }
+  /**
+   * Handles incoming WebSocket messages for the active chat session.
+   * @param {Object} data - Parsed message object
+   */
+  _handleChatMessage(data) {
+    try {
+      // Assertion: WebSocket topic scoping guarantees sessionId match.
+      // This warn is a safety net — if it fires, something is wrong upstream.
+      if (data.sessionId !== this.currentSessionId) {
+        console.warn(`[ChatPanel] Unexpected sessionId mismatch: got ${data.sessionId}, expected ${this.currentSessionId}`);
+        return;
+      }
 
-        // When the panel is closed, still accumulate internal state
-        // so messages are available when the panel reopens.
-        if (!this.isOpen) {
-          switch (data.type) {
-            case 'delta':
-              this._streamingContent += data.text;
-              break;
-            case 'complete':
-              if (this._streamingContent) {
-                this.messages.push({ role: 'assistant', content: this._streamingContent, id: data.messageId });
-              }
-              this._streamingContent = '';
-              this.isStreaming = false;
-              break;
-            case 'error':
-              this._streamingContent = '';
-              this.isStreaming = false;
-              break;
-            // tool_use, status: purely visual, skip when closed
-          }
-          return;
-        }
+      if (data.type !== 'delta') {
+        console.debug('[ChatPanel] WS event:', data.type, 'session:', data.sessionId);
+      }
 
+      // When the panel is closed, still accumulate internal state
+      // so messages are available when the panel reopens.
+      if (!this.isOpen) {
         switch (data.type) {
           case 'delta':
-            this._hideThinkingIndicator();
             this._streamingContent += data.text;
-            this.updateStreamingMessage(this._streamingContent);
-            break;
-
-          case 'tool_use':
-            this._showToolUse(data.toolName, data.status, data.toolInput);
             break;
-
-          case 'status':
-            this._handleAgentStatus(data.status);
-            break;
-
           case 'complete':
-            this.finalizeStreamingMessage(data.messageId);
+            if (this._streamingContent) {
+              this.messages.push({ role: 'assistant', content: this._streamingContent, id: data.messageId });
+            }
+            this._streamingContent = '';
+            this.isStreaming = false;
             break;
-
           case 'error':
-            this._showError(data.message || 'An error occurred');
-            this._finalizeStreaming();
+            this._streamingContent = '';
+            this.isStreaming = false;
             break;
+          // tool_use, status: purely visual, skip when closed
         }
-      } catch (e) {
-        console.error('[ChatPanel] SSE parse error:', e);
+        return;
       }
-    };
 
-    this.eventSource.onerror = () => {
-      if (this.eventSource?.readyState === EventSource.CLOSED) {
-        console.warn('[ChatPanel] Multiplexed SSE connection closed, reconnecting in 2s');
-        this.eventSource = null;
-        this._sseReconnectTimer = setTimeout(() => {
-          this._ensureGlobalSSE();
-        }, 2000);
+      switch (data.type) {
+        case 'delta':
+          this._hideThinkingIndicator();
+          this._streamingContent += data.text;
+          this.updateStreamingMessage(this._streamingContent);
+          break;
+
+        case 'tool_use':
+          this._showToolUse(data.toolName, data.status, data.toolInput);
+          break;
+
+        case 'status':
+          this._handleAgentStatus(data.status);
+          break;
+
+        case 'complete':
+          this.finalizeStreamingMessage(data.messageId);
+          break;
+
+        case 'error':
+          this._showError(data.message || 'An error occurred');
+          this._finalizeStreaming();
+          break;
       }
-    };
+    } catch (e) {
+      console.error('[ChatPanel] WS parse error:', e);
+    }
   }
 
   /**
-   * Close the global SSE connection and cancel any reconnect timer.
+   * Close all WebSocket subscriptions (chat and review).
    */
-  _closeGlobalSSE() {
-    clearTimeout(this._sseReconnectTimer);
-    this._sseReconnectTimer = null;
-    if (this.eventSource) {
-      this.eventSource.close();
-      this.eventSource = null;
+  _closeSubscriptions() {
+    if (this._chatUnsub) { this._chatUnsub(); this._chatUnsub = null; }
+    if (this._reviewUnsub) { this._reviewUnsub(); this._reviewUnsub = null; }
+    if (this._onReconnect) {
+      window.removeEventListener('wsReconnected', this._onReconnect);
+      this._onReconnect = null;
     }
   }
 
@@ -2930,7 +2991,7 @@ class ChatPanel {
    */
   destroy() {
     document.removeEventListener('keydown', this._onKeydown);
-    this._closeGlobalSSE();
+    this._closeSubscriptions();
     this.messages = [];
 
     // Clean up context tooltip
@@ -2946,6 +3007,9 @@ class ChatPanel {
   }
 }
 
+/** Resize configuration for the chat panel, exposed as a static for cross-module use. */
+ChatPanel.RESIZE_CONFIG = { min: 300, default: 400, cssVar: '--chat-panel-width', storageKey: 'chat-panel-width' };
+
 // Make ChatPanel available globally
 window.ChatPanel = ChatPanel;