@qwickapps/qwickbrain-proxy 1.0.0

package/src/lib/__tests__/qwickbrain-client.test.ts

@@ -0,0 +1,310 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { QwickBrainClient } from '../qwickbrain-client.js';
+import type { Config } from '../../types/config.js';
+
+// Mock the MCP SDK
+vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
+  Client: vi.fn().mockImplementation(() => ({
+    connect: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn().mockResolvedValue(undefined),
+    callTool: vi.fn(),
+    listTools: vi.fn().mockResolvedValue({ tools: [] }),
+  })),
+}));
+
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => ({
+  StdioClientTransport: vi.fn(),
+}));
+
+vi.mock('@modelcontextprotocol/sdk/client/sse.js', () => ({
+  SSEClientTransport: vi.fn(),
+}));
+
+// Mock fetch for HTTP mode
+global.fetch = vi.fn();
+
+describe('QwickBrainClient', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('SSE mode', () => {
+    let client: QwickBrainClient;
+    let config: Config['qwickbrain'];
+
+    beforeEach(() => {
+      config = {
+        mode: 'sse',
+        url: 'http://test.local:3000',
+      };
+
+      client = new QwickBrainClient(config);
+    });
+
+    it('should connect in SSE mode', async () => {
+      await client.connect();
+
+      expect(client['mode']).toBe('sse');
+      expect(client['client']).toBeDefined();
+    });
+
+    it('should get document via MCP in SSE mode', async () => {
+      await client.connect();
+
+      const mockResponse = {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              document: {
+                content: 'test content',
+                metadata: { version: 1 },
+              },
+            }),
+          },
+        ],
+      };
+
+      (client['client']!.callTool as any).mockResolvedValue(mockResponse);
+
+      const result = await client.getDocument('workflow', 'test');
+
+      expect(result.content).toBe('test content');
+      expect(result.metadata).toEqual({ version: 1 });
+    });
+
+    it('should throw on invalid MCP response format', async () => {
+      await client.connect();
+
+      const mockResponse = {
+        content: [
+          {
+            type: 'image', // Invalid type
+            data: 'invalid',
+          },
+        ],
+      };
+
+      (client['client']!.callTool as any).mockResolvedValue(mockResponse);
+
+      await expect(client.getDocument('workflow', 'test')).rejects.toThrow();
+    });
+  });
+
+  describe('HTTP mode', () => {
+    let client: QwickBrainClient;
+    let config: Config['qwickbrain'];
+
+    beforeEach(() => {
+      config = {
+        mode: 'http',
+        url: 'http://api.test.com',
+        apiKey: 'test-key',
+      };
+
+      client = new QwickBrainClient(config);
+    });
+
+    it('should get document via HTTP', async () => {
+      const mockResponse = {
+        content: 'test content',
+        metadata: { version: 1 },
+      };
+
+      (global.fetch as any).mockResolvedValue({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const result = await client.getDocument('workflow', 'test');
+
+      expect(result.content).toBe('test content');
+      expect(result.metadata).toEqual({ version: 1 });
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        'http://api.test.com/mcp/document',
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+            'Authorization': 'Bearer test-key',
+          }),
+        })
+      );
+    });
+
+    it('should throw on HTTP error', async () => {
+      (global.fetch as any).mockResolvedValue({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+      });
+
+      await expect(client.getDocument('workflow', 'test')).rejects.toThrow('HTTP 404');
+    });
+
+    it('should validate HTTP response schema', async () => {
+      const invalidResponse = {
+        // Missing required 'content' field
+        metadata: {},
+      };
+
+      (global.fetch as any).mockResolvedValue({
+        ok: true,
+        json: async () => invalidResponse,
+      });
+
+      await expect(client.getDocument('workflow', 'test')).rejects.toThrow();
+    });
+
+    it('should get memory via HTTP', async () => {
+      const mockResponse = {
+        content: 'memory content',
+        metadata: {},
+      };
+
+      (global.fetch as any).mockResolvedValue({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const result = await client.getMemory('test-memory');
+
+      expect(result.content).toBe('memory content');
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        'http://api.test.com/mcp/memory',
+        expect.objectContaining({
+          method: 'POST',
+        })
+      );
+    });
+  });
+
+  describe('MCP mode', () => {
+    let client: QwickBrainClient;
+    let config: Config['qwickbrain'];
+
+    beforeEach(() => {
+      config = {
+        mode: 'mcp',
+        command: 'npx',
+        args: ['qwickbrain-server'],
+      };
+
+      client = new QwickBrainClient(config);
+    });
+
+    it('should connect in MCP mode', async () => {
+      await client.connect();
+
+      expect(client['mode']).toBe('mcp');
+      expect(client['client']).toBeDefined();
+    });
+
+    it('should require command in MCP mode', async () => {
+      const invalidConfig: Config['qwickbrain'] = {
+        mode: 'mcp',
+        // Missing command
+      };
+
+      const invalidClient = new QwickBrainClient(invalidConfig);
+
+      await expect(invalidClient.connect()).rejects.toThrow('MCP mode requires command');
+    });
+  });
+
+  describe('healthCheck', () => {
+    it('should return true for successful MCP health check', async () => {
+      const config: Config['qwickbrain'] = {
+        mode: 'sse',
+        url: 'http://test.local:3000',
+      };
+
+      const client = new QwickBrainClient(config);
+      await client.connect();
+
+      const isHealthy = await client.healthCheck();
+
+      expect(isHealthy).toBe(true);
+    });
+
+    it('should return true for successful HTTP health check', async () => {
+      const config: Config['qwickbrain'] = {
+        mode: 'http',
+        url: 'http://api.test.com',
+      };
+
+      const client = new QwickBrainClient(config);
+
+      (global.fetch as any).mockResolvedValue({
+        ok: true,
+      });
+
+      const isHealthy = await client.healthCheck();
+
+      expect(isHealthy).toBe(true);
+      expect(global.fetch).toHaveBeenCalledWith('http://api.test.com/health');
+    });
+
+    it('should return false on health check failure', async () => {
+      const config: Config['qwickbrain'] = {
+        mode: 'sse',
+        url: 'http://test.local:3000',
+      };
+
+      const client = new QwickBrainClient(config);
+      await client.connect();
+
+      (client['client']!.listTools as any).mockRejectedValue(new Error('Failed'));
+
+      const isHealthy = await client.healthCheck();
+
+      expect(isHealthy).toBe(false);
+    });
+
+    it('should return false for missing URL in HTTP mode', async () => {
+      const config: Config['qwickbrain'] = {
+        mode: 'http',
+        // Missing URL
+      };
+
+      const client = new QwickBrainClient(config);
+
+      const isHealthy = await client.healthCheck();
+
+      expect(isHealthy).toBe(false);
+    });
+  });
+
+  describe('disconnect', () => {
+    it('should disconnect MCP client', async () => {
+      const config: Config['qwickbrain'] = {
+        mode: 'sse',
+        url: 'http://test.local:3000',
+      };
+
+      const client = new QwickBrainClient(config);
+      await client.connect();
+
+      const closeMock = client['client']!.close;
+
+      await client.disconnect();
+
+      expect(closeMock).toHaveBeenCalled();
+      expect(client['client']).toBeNull();
+    });
+
+    it('should handle disconnect when not connected', async () => {
+      const config: Config['qwickbrain'] = {
+        mode: 'http',
+        url: 'http://api.test.com',
+      };
+
+      const client = new QwickBrainClient(config);
+
+      // Should not throw
+      await expect(client.disconnect()).resolves.toBeUndefined();
+    });
+  });
+});

package/src/lib/cache-manager.ts

@@ -0,0 +1,201 @@
+import { eq, and, lt, lte, sql } from 'drizzle-orm';
+import type { DB } from '../db/client.js';
+import { documents, memories } from '../db/schema.js';
+import type { Config } from '../types/config.js';
+
+interface CachedItem<T> {
+  data: T;
+  cachedAt: Date;
+  expiresAt: Date;
+  age: number; // seconds
+  isExpired: boolean;
+}
+
+export class CacheManager {
+  constructor(
+    private db: DB,
+    private config: Config['cache']
+  ) {}
+
+  private getTTL(operation: string): number {
+    const ttlMap: Record<string, number> = {
+      get_workflow: this.config.ttl.workflows,
+      get_document: this.config.ttl.documents,
+      get_memory: this.config.ttl.memories,
+    };
+
+    return ttlMap[operation] || 0;
+  }
+
+  async getDocument(docType: string, name: string, project?: string): Promise<CachedItem<any> | null> {
+    const projectValue = project || '';
+
+    const [cached] = await this.db
+      .select()
+      .from(documents)
+      .where(
+        and(
+          eq(documents.docType, docType),
+          eq(documents.name, name),
+          eq(documents.project, projectValue)
+        )
+      )
+      .limit(1);
+
+    if (!cached) {
+      return null;
+    }
+
+    const now = new Date();
+    const age = Math.floor((now.getTime() - cached.cachedAt.getTime()) / 1000);
+    // Fix: Compare timestamp values explicitly to avoid Date comparison issues
+    const isExpired = now.getTime() > cached.expiresAt.getTime();
+
+    return {
+      data: {
+        name: cached.name,
+        doc_type: cached.docType,
+        project: cached.project,
+        content: cached.content,
+        metadata: cached.metadata ? JSON.parse(cached.metadata) : {},
+      },
+      cachedAt: cached.cachedAt,
+      expiresAt: cached.expiresAt,
+      age,
+      isExpired,
+    };
+  }
+
+  async setDocument(
+    docType: string,
+    name: string,
+    content: string,
+    project?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    const now = new Date();
+    const ttl = this.getTTL('get_document');
+    const expiresAt = new Date(now.getTime() + ttl * 1000);
+
+    // Use empty string instead of null for project to make unique constraint work
+    // SQLite treats NULL as distinct values in unique constraints
+    const projectValue = project || '';
+
+    await this.db
+      .insert(documents)
+      .values({
+        docType,
+        name,
+        project: projectValue,
+        content,
+        metadata: metadata ? JSON.stringify(metadata) : null,
+        cachedAt: now,
+        expiresAt,
+        synced: true,
+      })
+      .onConflictDoUpdate({
+        target: [documents.docType, documents.name, documents.project],
+        set: {
+          content,
+          metadata: metadata ? JSON.stringify(metadata) : null,
+          cachedAt: now,
+          expiresAt,
+          synced: true,
+        },
+      });
+  }
+
+  async getMemory(name: string, project?: string): Promise<CachedItem<any> | null> {
+    const projectValue = project || '';
+
+    const [cached] = await this.db
+      .select()
+      .from(memories)
+      .where(
+        and(
+          eq(memories.name, name),
+          eq(memories.project, projectValue)
+        )
+      )
+      .limit(1);
+
+    if (!cached) {
+      return null;
+    }
+
+    const now = new Date();
+    const age = Math.floor((now.getTime() - cached.cachedAt.getTime()) / 1000);
+    // Fix: Compare timestamp values explicitly to avoid Date comparison issues
+    const isExpired = now.getTime() > cached.expiresAt.getTime();
+
+    return {
+      data: {
+        name: cached.name,
+        project: cached.project,
+        content: cached.content,
+        metadata: cached.metadata ? JSON.parse(cached.metadata) : {},
+      },
+      cachedAt: cached.cachedAt,
+      expiresAt: cached.expiresAt,
+      age,
+      isExpired,
+    };
+  }
+
+  async setMemory(
+    name: string,
+    content: string,
+    project?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    const now = new Date();
+    const ttl = this.getTTL('get_memory');
+    const expiresAt = new Date(now.getTime() + ttl * 1000);
+
+    // Use empty string instead of null for project to make unique constraint work
+    const projectValue = project || '';
+
+    await this.db
+      .insert(memories)
+      .values({
+        name,
+        project: projectValue,
+        content,
+        metadata: metadata ? JSON.stringify(metadata) : null,
+        cachedAt: now,
+        expiresAt,
+        synced: true,
+      })
+      .onConflictDoUpdate({
+        target: [memories.name, memories.project],
+        set: {
+          content,
+          metadata: metadata ? JSON.stringify(metadata) : null,
+          cachedAt: now,
+          expiresAt,
+          synced: true,
+        },
+      });
+  }
+
+  async cleanupExpiredEntries(): Promise<{ documentsDeleted: number; memoriesDeleted: number }> {
+    const now = new Date();
+
+    // Delete expired documents (use lte to include items expiring exactly now)
+    const deletedDocs = await this.db
+      .delete(documents)
+      .where(lte(documents.expiresAt, now))
+      .returning({ id: documents.id });
+
+    // Delete expired memories (use lte to include items expiring exactly now)
+    const deletedMems = await this.db
+      .delete(memories)
+      .where(lte(memories.expiresAt, now))
+      .returning({ id: memories.id });
+
+    return {
+      documentsDeleted: deletedDocs.length,
+      memoriesDeleted: deletedMems.length,
+    };
+  }
+}

package/src/lib/connection-manager.ts

@@ -0,0 +1,156 @@
+import { EventEmitter } from 'events';
+import { ConnectionState } from '../types/mcp.js';
+import type { Config } from '../types/config.js';
+import type { QwickBrainClient } from './qwickbrain-client.js';
+
+export class ConnectionManager extends EventEmitter {
+  private state: ConnectionState = 'disconnected';
+  private reconnectAttempts = 0;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private healthCheckTimer: NodeJS.Timeout | null = null;
+  private qwickbrainClient: QwickBrainClient;
+  private config: Config['connection'];
+  private isStopped = false;
+  private executionLock: Promise<void> = Promise.resolve();
+
+  constructor(qwickbrainClient: QwickBrainClient, config: Config['connection']) {
+    super();
+    this.qwickbrainClient = qwickbrainClient;
+    this.config = config;
+  }
+
+  getState(): ConnectionState {
+    return this.state;
+  }
+
+  setState(state: ConnectionState): void {
+    const previousState = this.state;
+    this.state = state;
+
+    if (previousState !== state) {
+      this.emit('stateChange', { from: previousState, to: state });
+    }
+  }
+
+  async start(): Promise<void> {
+    this.isStopped = false;
+    await this.healthCheck();
+    this.scheduleHealthCheck();
+  }
+
+  stop(): void {
+    this.isStopped = true;
+    if (this.healthCheckTimer) {
+      clearTimeout(this.healthCheckTimer);
+      this.healthCheckTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.setState('offline');
+  }
+
+  async healthCheck(): Promise<boolean> {
+    const startTime = Date.now();
+
+    try {
+      const isHealthy = await this.qwickbrainClient.healthCheck();
+      const latencyMs = Date.now() - startTime;
+
+      if (isHealthy) {
+        this.setState('connected');
+        this.reconnectAttempts = 0;
+        this.clearReconnectTimer();
+        this.emit('connected', { latencyMs });
+        return true;
+      } else {
+        throw new Error('Health check failed');
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.setState('disconnected');
+      this.emit('disconnected', { error: errorMessage });
+      this.scheduleReconnect();
+      return false;
+    }
+  }
+
+  private scheduleHealthCheck(): void {
+    // Don't schedule if stopped
+    if (this.isStopped) {
+      return;
+    }
+
+    if (this.healthCheckTimer) {
+      clearTimeout(this.healthCheckTimer);
+    }
+
+    this.healthCheckTimer = setTimeout(async () => {
+      await this.healthCheck();
+      // Check again before rescheduling to prevent leak after stop()
+      if (!this.isStopped) {
+        this.scheduleHealthCheck();
+      }
+    }, this.config.healthCheckInterval);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) {
+      return; // Already scheduled
+    }
+
+    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      this.setState('offline');
+      this.emit('maxReconnectAttemptsReached');
+      return;
+    }
+
+    const delay = Math.min(
+      this.config.reconnectBackoff.initial *
+        Math.pow(this.config.reconnectBackoff.multiplier, this.reconnectAttempts),
+      this.config.reconnectBackoff.max
+    );
+
+    this.reconnectAttempts++;
+    this.setState('reconnecting');
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      await this.healthCheck();
+    }, delay);
+
+    this.emit('reconnecting', { attempt: this.reconnectAttempts, delay });
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  recordFailure(): void {
+    if (this.state === 'connected') {
+      this.setState('disconnected');
+      this.scheduleReconnect();
+    }
+  }
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Wait for any ongoing state transitions to complete
+    await this.executionLock;
+
+    // Atomically check state and execute
+    if (this.state !== 'connected') {
+      throw new Error(`QwickBrain unavailable (state: ${this.state})`);
+    }
+
+    try {
+      return await fn();
+    } catch (error) {
+      this.recordFailure();
+      throw error;
+    }
+  }
+}