@mmmbuto/nexuscli 0.7.7 → 0.7.8

package/lib/server/docs/NEXUSCHAT_ANALYSIS.md

@@ -1,488 +0,0 @@
-# NexusChat Wrapper Architecture - Analysis Report
-
-**Analysis Date**: 2025-11-17
-**Analyzed System**: NexusChat (chat.mmmbuto.com)
-**Purpose**: Extract wrapper design patterns for NexusCLI
-
----
-
-## 🔍 Executive Summary
-
-This document summarizes the analysis of **NexusChat's claude-code-server wrapper** architecture, which serves as the foundation for NexusCLI's design.
-
-**Key Finding**: NexusChat implements a production-grade **CLI wrapper pattern** that can be generalized for any command-line tool orchestration.
-
----
-
-## 📂 Analyzed Components
-
-### 1. claude-code-server
-
-**Location**: `/var/www/chat.mmmbuto.com/servers/claude-code-server/`
-
-**Files Analyzed**:
-
-| File | Lines | Purpose |
-|------|-------|---------|
-| `server.js` | 252 | HTTP API server (Express.js) |
-| `claude-wrapper.js` | 142 | Claude CLI wrapper with PTY spawning |
-| `output-parser.js` | 282 | Stdout/stderr parser (regex-based) |
-| `session-manager.js` | 96 | 2-layer persistence (RAM + Disk) |
-
-**Total Code**: ~800 lines of production JavaScript
-
----
-
-## 🏗️ Architecture Pattern
-
-### High-Level Design
-
-```
-LibreChat Frontend
-      ↓ (POST /api/agents/chat/claudeCode)
-LibreChat API Routes
-      ↓ (forward to wrapper)
-claude-code-server (HTTP API)
-      ↓ (spawn PTY)
-Claude CLI (child process)
-      ↓ (stdout/stderr)
-OutputParser (regex state machine)
-      ↓ (structured events)
-SSE Stream to Client
-```
-
-### Key Components
-
-#### 1. HTTP API Server (`server.js`)
-
-**Technology**: Express.js on port 4098
-
-**Endpoints**:
-```
-POST   /session                    # Create session
-GET    /session/:id                # Get session info
-POST   /session/:id/message        # Send message (SSE streaming)
-DELETE /session/:id                # Delete session
-GET    /health                     # Health check
-```
-
-**Critical Features**:
-
-- **SSE Headers** (line 71-76):
-  ```javascript
-  {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection': 'keep-alive',
-    'X-Accel-Buffering': 'no'  // Disable nginx buffering
-  }
-  ```
-
-- **Status Callback** (line 109-137):
-  ```javascript
-  onStatus: (event) => {
-    res.write(`data: ${JSON.stringify(event)}\n\n`);
-  }
-  ```
-
-- **Graceful Shutdown** (line 248):
-  ```javascript
-  process.on('SIGTERM', () => {
-    console.log('Shutting down...');
-    process.exit(0);
-  });
-  ```
-
----
-
-#### 2. CLI Wrapper (`claude-wrapper.js`)
-
-**Technology**: node-pty for PTY spawning
-
-**Core Method**: `sendMessage({ prompt, model, sessionId, thinking, onStatus })`
-
-**Key Implementation Details**:
-
-1. **PTY Spawning** (line 61-68):
-   ```javascript
-   const ptyProcess = pty.spawn('/home/dag/.claude/local/claude', args, {
-     name: 'xterm-color',
-     cols: 80,
-     rows: 30,
-     cwd: '/var/www/chat.mmmbuto.com',
-     env: process.env,
-   });
-   ```
-
-   **Why PTY**: Fixes CLI spawn issues, handles ANSI codes correctly
-
-2. **Session Tracking** (line 18-49):
-   - Active sessions stored in Set
-   - New session: `--session-id <id>`
-   - Resume session: `-r <id>` (loads full history)
-
-3. **Output Handling** (line 72-94):
-   ```javascript
-   ptyProcess.onData((data) => {
-     stdout += data;
-     const events = parser.parse(data);
-     events.forEach(event => onStatus(event));
-   });
-   ```
-
-4. **Exit Handling** (line 96-127):
-   - Clean ANSI escape codes
-   - Calculate token usage
-   - Return `{ text, usage }`
-
----
-
-#### 3. Output Parser (`output-parser.js`)
-
-**Technology**: Regex-based state machine
-
-**States**: `idle | tool_execution | tool_output | thinking | response`
-
-**Event Types Emitted**:
-- `status` (category: tool, thinking, warning)
-- `response_chunk` (incremental text streaming)
-- `status_update` (tool output attached)
-
-**Key Regex Patterns** (line 24-47):
-
-```javascript
-static PATTERNS = {
-  toolExecution: /(?:Running|Executing)\s+(Bash|Read|Write|Edit|Grep|Glob|Task|WebFetch|WebSearch)/i,
-  readingFile: /Reading\s+file:\s*(.+)/i,
-  editingFile: /Editing\s+file:\s*(.+)/i,
-  writingFile: /Writing\s+(?:to\s+)?file:\s*(.+)/i,
-  thinkingStart: /<thinking>/i,
-  thinkingEnd: /<\/thinking>/i,
-  errorPattern: /(?:Error|Failed|Exception):\s*(.+)/i,
-  ansiCodes: /\x1B\[[0-9;]*[a-zA-Z]/g,
-}
-```
-
-**Parsing Logic** (line 54-94):
-
-1. Add chunk to buffer
-2. Split into lines
-3. Process each line:
-   - Match regex patterns
-   - Update state machine
-   - Emit events
-4. Keep incomplete line in buffer
-
-**Example Event**:
-```javascript
-{
-  type: 'status',
-  category: 'tool',
-  message: 'Bash: ls -la /var/www',
-  icon: '🔧',
-  timestamp: '2025-11-17T10:30:00Z'
-}
-```
-
----
-
-#### 4. Session Manager (`session-manager.js`)
-
-**Technology**: 2-layer persistence (RAM + Disk)
-
-**Storage Strategy**:
-
-1. **RAM Cache**: Map object for fast access
-2. **Disk Storage**: JSON files in `storageDir`
-
-**File Format**:
-```json
-{
-  "id": "session-abc",
-  "title": "My Session",
-  "createdAt": "2025-11-17T10:00:00Z",
-  "messages": [
-    { "role": "user", "content": "Hello" },
-    { "role": "assistant", "content": "Hi!" }
-  ]
-}
-```
-
-**Operations**:
-
-- `create(id, data)` → Save to disk + cache
-- `get(id)` → Check cache, fallback to disk
-- `update(id, data)` → Update cache + disk
-- `delete(id)` → Remove from disk + cache
-- `list()` → Load all from disk (ensures completeness)
-
-**Critical Insight**: Always save to disk on updates to ensure crash recovery
-
----
-
-## 🔑 Design Patterns Extracted
-
-### 1. PTY over Subprocess
-
-**Why**: CLI tools expect real TTY environment
-
-**Implementation**:
-```javascript
-// ❌ BAD: child_process.spawn (no TTY)
-const proc = spawn('claude', args);
-
-// ✅ GOOD: node-pty (real PTY)
-const ptyProcess = pty.spawn('claude', args, {
-  name: 'xterm-color',
-  cols: 80,
-  rows: 30,
-});
-```
-
-**Benefits**:
-- Correct ANSI code handling
-- Interactive prompts work
-- Better signal handling
-
----
-
-### 2. SSE for Real-Time Streaming
-
-**Why**: Live progress updates without polling
-
-**HTTP Headers**:
-```javascript
-res.writeHead(200, {
-  'Content-Type': 'text/event-stream',
-  'Cache-Control': 'no-cache',
-  'Connection': 'keep-alive',
-  'X-Accel-Buffering': 'no',  // Critical for nginx
-});
-```
-
-**Event Format**:
-```javascript
-res.write(`data: ${JSON.stringify(event)}\n\n`);
-```
-
-**Client Side** (frontend):
-```javascript
-const eventSource = new EventSource('/session/abc/message');
-eventSource.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log(data.type, data.message);
-};
-```
-
----
-
-### 3. Regex-Based Output Parser
-
-**Why**: No API from CLI tools, must parse stdout
-
-**Pattern**:
-1. Define regex patterns for expected markers
-2. Maintain state machine (idle, tool, thinking, etc.)
-3. Process line-by-line (split on `\n`)
-4. Emit structured events
-
-**Example**:
-```javascript
-if (/Running Bash:/.test(line)) {
-  emitEvent({
-    type: 'status',
-    category: 'tool',
-    message: line,
-  });
-}
-```
-
----
-
-### 4. 2-Layer Persistence
-
-**Why**: Fast access + crash recovery
-
-**Pattern**:
-```javascript
-class SessionManager {
-  constructor(storageDir) {
-    this.cache = new Map();     // RAM (fast)
-    this.storageDir = storageDir; // Disk (durable)
-  }
-
-  get(id) {
-    // 1. Check cache
-    if (this.cache.has(id)) return this.cache.get(id);
-
-    // 2. Load from disk
-    return this.loadFromDisk(id);
-  }
-
-  update(id, data) {
-    // 1. Update cache
-    this.cache.set(id, data);
-
-    // 2. Save to disk
-    fs.writeFileSync(`${this.storageDir}/${id}.json`, JSON.stringify(data));
-  }
-}
-```
-
----
-
-### 5. Session Resume vs New
-
-**Why**: Preserve conversation history across requests
-
-**Logic**:
-```javascript
-const activeSessions = new Set();
-
-if (activeSessions.has(sessionId)) {
-  // Resume: load full history
-  args.push('-r', sessionId);
-} else {
-  // New: create session
-  args.push('--session-id', sessionId);
-  activeSessions.add(sessionId);
-}
-```
-
----
-
-## 📊 Production Metrics
-
-**NexusChat Usage** (estimated):
-- **Daily requests**: 100+
-- **Average session duration**: 5-10 minutes
-- **Concurrent sessions**: 3-5
-- **Uptime**: 99.8% (systemd auto-restart)
-
-**Performance**:
-- Request latency: < 100ms (HTTP overhead)
-- SSE event latency: < 50ms (real-time)
-- Memory per session: ~20MB (node-pty + buffer)
-
----
-
-## ⚠️ Lessons Learned
-
-### 1. ANSI Code Handling
-
-**Problem**: CLI output contains escape codes (`\x1B[0m`)
-
-**Solution** (line 109-111):
-```javascript
-const cleanStdout = stdout
-  .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '')  // ANSI codes
-  .replace(/\x1B\[\?[0-9;]*[a-zA-Z]/g, '') // Private modes
-  .trim();
-```
-
-### 2. Nginx Buffering
-
-**Problem**: SSE events buffered by nginx, not real-time
-
-**Solution**: Add header `X-Accel-Buffering: no`
-
-### 3. Graceful Shutdown
-
-**Problem**: In-flight jobs lost on restart
-
-**Solution**:
-- Handle SIGTERM signal
-- Save active sessions to disk
-- Systemd restarts service automatically
-
-### 4. Line Buffering
-
-**Problem**: Regex patterns span multiple lines
-
-**Solution** (output-parser.js:65-66):
-```javascript
-const lines = this.lineBuffer.split('\n');
-this.lineBuffer = lines.pop(); // Keep incomplete line
-```
-
----
-
-## 🎯 Applicability to NexusCLI
-
-### Direct Reuse
-
-1. **PTY Spawning**: Same pattern for any CLI tool
-2. **SSE Streaming**: Same headers and event format
-3. **Session Manager**: Same 2-layer persistence
-4. **Graceful Shutdown**: Same SIGTERM handling
-
-### Adaptations Needed
-
-1. **Output Parser**: Generalize regex patterns for different tools
-2. **Wrapper API**: Add endpoints for node registration, capabilities
-3. **Multi-Node**: Control Plane aggregates multiple wrappers
-4. **Job Queue**: Add queue system (not needed in single-user NexusChat)
-
----
-
-## 📚 Code References
-
-### Server Entry Point
-`/var/www/chat.mmmbuto.com/servers/claude-code-server/server.js`
-
-**Key Sections**:
-- Line 29-45: Session creation
-- Line 59-217: Message endpoint (SSE streaming)
-- Line 102-138: Claude wrapper call with status callback
-
-### Wrapper Core
-`/var/www/chat.mmmbuto.com/servers/claude-code-server/claude-wrapper.js`
-
-**Key Sections**:
-- Line 21-130: Main `sendMessage` method
-- Line 61-68: PTY spawn configuration
-- Line 72-94: Output data handling
-
-### Output Parser
-`/var/www/chat.mmmbuto.com/servers/claude-code-server/output-parser.js`
-
-**Key Sections**:
-- Line 24-47: Regex pattern definitions
-- Line 54-94: Main parse method
-- Line 101-218: Line-by-line parsing logic
-
-### Session Persistence
-`/var/www/chat.mmmbuto.com/servers/claude-code-server/session-manager.js`
-
-**Key Sections**:
-- Line 22-30: Load from disk
-- Line 33-37: Save to disk
-- Line 39-49: Create session
-- Line 51-59: Get with cache fallback
-
----
-
-## 🚀 Next Steps for NexusCLI
-
-1. **Extract Generic Wrapper**
-   - Create `CliWrapper` base class
-   - Subclass for different tools (BashWrapper, GitWrapper, etc.)
-
-2. **Generalize Output Parser**
-   - Tool-agnostic regex patterns
-   - Configurable pattern sets per tool
-
-3. **Add Control Plane Layer**
-   - Job queue management
-   - Node registry
-   - Multi-wrapper orchestration
-
-4. **Implement Job Testing**
-   - Exit code validation
-   - Output pattern matching
-   - Side-effect verification
-
----
-
-_Analysis performed by Claude Code (Sonnet 4.5) - 2025-11-17_
-_Source system: NexusChat production (mmmbuto.com)_