tlc-claude-code 1.7.0 → 1.8.0

package/server/lib/llm/index.test.js

@@ -0,0 +1,147 @@
+/**
+ * LLM Service Integration Tests
+ *
+ * Unified API: createLLMService(config) → { review, execute, health }
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  createLLMService,
+} = require('./index.js');
+
+describe('LLM Service', () => {
+  const mockDeps = {
+    healthCheck: vi.fn().mockResolvedValue({ available: true }),
+    spawn: vi.fn().mockReturnValue({
+      stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('{"findings": [], "summary": "Clean"}')); }) },
+      stderr: { on: vi.fn() },
+      stdin: { write: vi.fn(), end: vi.fn() },
+      on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+    }),
+  };
+
+  describe('createLLMService', () => {
+    it('creates service with config', () => {
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['review'] },
+        },
+      }, mockDeps);
+
+      expect(service).toBeDefined();
+      expect(service.review).toBeDefined();
+      expect(service.execute).toBeDefined();
+      expect(service.health).toBeDefined();
+    });
+
+    it('creates service with zero config (auto-detect)', () => {
+      const service = createLLMService({}, mockDeps);
+      expect(service).toBeDefined();
+    });
+
+    it('review() returns structured findings', async () => {
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['review'] },
+        },
+      }, mockDeps);
+
+      const result = await service.review('diff content');
+      expect(result).toMatchObject({
+        findings: expect.any(Array),
+        summary: expect.any(String),
+      });
+    });
+
+    it('execute() returns raw response', async () => {
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['code-gen'] },
+        },
+      }, mockDeps);
+
+      const result = await service.execute('Write a function');
+      expect(result).toMatchObject({
+        response: expect.any(String),
+      });
+    });
+
+    it('health() returns provider statuses', async () => {
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['review'] },
+        },
+      }, mockDeps);
+
+      const status = await service.health();
+      expect(status.providers).toBeDefined();
+    });
+
+    it('falls back through providers on failure', async () => {
+      const failThenSucceed = vi.fn()
+        .mockReturnValueOnce({
+          stdout: { on: vi.fn() },
+          stderr: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('err')); }) },
+          stdin: { write: vi.fn(), end: vi.fn() },
+          on: vi.fn((ev, cb) => { if (ev === 'close') cb(1); }),
+        })
+        .mockReturnValueOnce({
+          stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('{"findings": [], "summary": "OK"}')); }) },
+          stderr: { on: vi.fn() },
+          stdin: { write: vi.fn(), end: vi.fn() },
+          on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+        });
+
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['review'] },
+          gemini: { type: 'cli', command: 'gemini', capabilities: ['review'] },
+        },
+      }, { ...mockDeps, spawn: failThenSucceed });
+
+      const result = await service.review('diff');
+      expect(result.findings).toBeDefined();
+    });
+
+    it('respects multi-model config', () => {
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['review'] },
+          gemini: { type: 'cli', command: 'gemini', capabilities: ['review'] },
+        },
+        multiModel: true,
+      }, mockDeps);
+
+      expect(service).toBeDefined();
+    });
+
+    it('works with single provider', () => {
+      const service = createLLMService({
+        providers: {
+          codex: { type: 'cli', command: 'codex', capabilities: ['review'] },
+        },
+      }, mockDeps);
+
+      expect(service).toBeDefined();
+    });
+
+    it('exports clean public API', () => {
+      const service = createLLMService({}, mockDeps);
+      const keys = Object.keys(service);
+      expect(keys).toContain('review');
+      expect(keys).toContain('execute');
+      expect(keys).toContain('health');
+    });
+
+    it('config validation catches bad provider references', () => {
+      // Should not throw, just log warning or skip bad providers
+      const service = createLLMService({
+        providers: {
+          invalid: { type: 'unknown', capabilities: ['review'] },
+        },
+      }, mockDeps);
+
+      expect(service).toBeDefined();
+    });
+  });
+});

package/server/lib/llm/provider-executor.js

@@ -0,0 +1,168 @@
+/**
+ * Provider Executor
+ *
+ * Actually execute LLM requests through any provider.
+ * The bridge between "provider detected" and "review completed."
+ * Supports CLI (spawn) and API (HTTP) providers.
+ *
+ * @module llm/provider-executor
+ */
+
+/** Strip ANSI escape codes from output */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+/**
+ * Execute a CLI provider by spawning the process
+ * @param {string} prompt - The prompt to send
+ * @param {Object} options - Execution options
+ * @param {string} options.command - CLI command to run
+ * @param {string[]} options.args - CLI arguments
+ * @param {Function} options.spawn - Spawn function (injectable)
+ * @param {number} options.timeout - Timeout in ms
+ * @returns {Promise<{response: string}>}
+ */
+function executeCliProvider(prompt, options = {}) {
+  const { command, args = [], spawn, timeout } = options;
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(command, args);
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timer;
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+
+      if (code !== 0) {
+        reject(new Error('Provider exited with exit code ' + code + ': ' + stderr));
+        return;
+      }
+
+      resolve({ response: stripAnsi(stdout) });
+    });
+
+    // Write prompt to stdin
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+
+    // Timeout handling
+    if (timeout) {
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        if (proc.kill) proc.kill();
+        reject(new Error('CLI provider timeout after ' + timeout + 'ms'));
+      }, timeout);
+    }
+  });
+}
+
+/**
+ * Execute an API provider via HTTP POST
+ * @param {string} prompt - The prompt to send
+ * @param {Object} options - Execution options
+ * @param {string} options.url - API endpoint URL
+ * @param {string} options.model - Model name
+ * @param {string} options.apiKey - API key
+ * @param {Function} options.fetch - Fetch function (injectable)
+ * @param {number} options.timeout - Timeout in ms
+ * @returns {Promise<{response: string, model: string, tokens: number}>}
+ */
+async function executeApiProvider(prompt, options = {}) {
+  const { url, model, apiKey, timeout } = options;
+  const fetchFn = options.fetch || globalThis.fetch;
+
+  const body = {
+    model,
+    messages: [{ role: 'user', content: prompt }],
+  };
+
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) {
+    headers['Authorization'] = 'Bearer ' + apiKey;
+  }
+
+  let fetchPromise = fetchFn(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (timeout) {
+    fetchPromise = Promise.race([
+      fetchPromise,
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('API provider timeout after ' + timeout + 'ms')), timeout)
+      ),
+    ]);
+  }
+
+  const resp = await fetchPromise;
+
+  if (!resp.ok) {
+    throw new Error('API returned status ' + resp.status);
+  }
+
+  const data = await resp.json();
+  const content = data.choices?.[0]?.message?.content || '';
+
+  return {
+    response: content,
+    model: data.model || model,
+    tokens: data.usage?.total_tokens || 0,
+  };
+}
+
+/**
+ * Create a unified executor with injectable dependencies
+ * @param {Object} deps - Dependencies
+ * @param {Function} deps.spawn - Spawn function
+ * @param {Function} deps.fetch - Fetch function
+ * @returns {Object} Executor with execute method
+ */
+function createExecutor(deps = {}) {
+  return {
+    execute: async (prompt, provider) => {
+      const start = Date.now();
+
+      let result;
+      if (provider.type === 'api') {
+        result = await executeApiProvider(prompt, {
+          ...provider,
+          fetch: deps.fetch,
+        });
+      } else {
+        result = await executeCliProvider(prompt, {
+          ...provider,
+          spawn: deps.spawn,
+        });
+      }
+
+      return {
+        response: result.response,
+        model: provider.model || provider.command || 'unknown',
+        latency: Date.now() - start,
+        tokens: result.tokens || 0,
+      };
+    },
+  };
+}
+
+module.exports = {
+  executeCliProvider,
+  executeApiProvider,
+  createExecutor,
+};

package/server/lib/llm/provider-executor.test.js

@@ -0,0 +1,244 @@
+/**
+ * Provider Executor Tests
+ *
+ * Actually execute LLM requests through any provider.
+ * The bridge between "provider detected" and "review completed."
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  executeCliProvider,
+  executeApiProvider,
+  createExecutor,
+} = require('./provider-executor.js');
+
+describe('Provider Executor', () => {
+  describe('executeCliProvider', () => {
+    it('executes CLI provider via spawn', async () => {
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('review result')); }) },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+      });
+
+      const result = await executeCliProvider('Review this code', {
+        command: 'codex',
+        args: [],
+        spawn: mockSpawn,
+      });
+
+      expect(mockSpawn).toHaveBeenCalled();
+      expect(result.response).toContain('review result');
+    });
+
+    it('passes prompt as stdin to CLI', async () => {
+      let writtenData = '';
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('ok')); }) },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn((d) => { writtenData = d; }), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+      });
+
+      await executeCliProvider('my prompt text', {
+        command: 'codex',
+        args: [],
+        spawn: mockSpawn,
+      });
+
+      expect(writtenData).toContain('my prompt text');
+    });
+
+    it('captures stdout as response', async () => {
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn((ev, cb) => {
+          if (ev === 'data') {
+            cb(Buffer.from('chunk1'));
+            cb(Buffer.from('chunk2'));
+          }
+        }) },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+      });
+
+      const result = await executeCliProvider('prompt', {
+        command: 'codex',
+        args: [],
+        spawn: mockSpawn,
+      });
+
+      expect(result.response).toBe('chunk1chunk2');
+    });
+
+    it('handles CLI timeout (kills process)', async () => {
+      const killFn = vi.fn();
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn() },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn(), // never calls close
+        kill: killFn,
+      });
+
+      await expect(
+        executeCliProvider('prompt', {
+          command: 'codex',
+          args: [],
+          spawn: mockSpawn,
+          timeout: 50,
+        })
+      ).rejects.toThrow(/timeout/i);
+    });
+
+    it('handles provider exit code != 0', async () => {
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn() },
+        stderr: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('error occurred')); }) },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(1); }),
+      });
+
+      await expect(
+        executeCliProvider('prompt', {
+          command: 'codex',
+          args: [],
+          spawn: mockSpawn,
+        })
+      ).rejects.toThrow(/exit code 1/i);
+    });
+
+    it('handles empty response', async () => {
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn() },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+      });
+
+      const result = await executeCliProvider('prompt', {
+        command: 'codex',
+        args: [],
+        spawn: mockSpawn,
+      });
+
+      expect(result.response).toBe('');
+    });
+
+    it('respects provider-specific args from config', async () => {
+      let spawnedArgs = [];
+      const mockSpawn = vi.fn().mockImplementation((cmd, args) => {
+        spawnedArgs = args;
+        return {
+          stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('ok')); }) },
+          stderr: { on: vi.fn() },
+          stdin: { write: vi.fn(), end: vi.fn() },
+          on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+        };
+      });
+
+      await executeCliProvider('prompt', {
+        command: 'codex',
+        args: ['--model', 'gpt-4o', '--quiet'],
+        spawn: mockSpawn,
+      });
+
+      expect(spawnedArgs).toContain('--model');
+      expect(spawnedArgs).toContain('gpt-4o');
+    });
+
+    it('strips ANSI codes from CLI output', async () => {
+      const ansiOutput = '\x1b[31mred text\x1b[0m normal';
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from(ansiOutput)); }) },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+      });
+
+      const result = await executeCliProvider('prompt', {
+        command: 'codex',
+        args: [],
+        spawn: mockSpawn,
+      });
+
+      expect(result.response).not.toContain('\x1b[');
+      expect(result.response).toContain('red text');
+    });
+  });
+
+  describe('executeApiProvider', () => {
+    it('executes API provider via HTTP POST', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: 'review response' } }],
+        }),
+      });
+
+      const result = await executeApiProvider('prompt', {
+        url: 'http://localhost:4000/v1/chat/completions',
+        model: 'gpt-4o',
+        apiKey: 'test-key',
+        fetch: mockFetch,
+      });
+
+      expect(result.response).toBe('review response');
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ method: 'POST' })
+      );
+    });
+
+    it('handles API timeout', async () => {
+      const mockFetch = vi.fn().mockImplementation(() =>
+        new Promise((resolve) => setTimeout(resolve, 10000))
+      );
+
+      await expect(
+        executeApiProvider('prompt', {
+          url: 'http://localhost:4000/v1/chat/completions',
+          model: 'gpt-4o',
+          fetch: mockFetch,
+          timeout: 50,
+        })
+      ).rejects.toThrow(/timeout/i);
+    });
+  });
+
+  describe('createExecutor', () => {
+    it('returns standardized { response, model, latency } format', async () => {
+      const mockSpawn = vi.fn().mockReturnValue({
+        stdout: { on: vi.fn((ev, cb) => { if (ev === 'data') cb(Buffer.from('result')); }) },
+        stderr: { on: vi.fn() },
+        stdin: { write: vi.fn(), end: vi.fn() },
+        on: vi.fn((ev, cb) => { if (ev === 'close') cb(0); }),
+      });
+
+      const executor = createExecutor({ spawn: mockSpawn });
+      const result = await executor.execute('prompt', {
+        type: 'cli',
+        command: 'codex',
+        args: [],
+        model: 'gpt-4o',
+      });
+
+      expect(result).toMatchObject({
+        response: expect.any(String),
+        model: 'gpt-4o',
+        latency: expect.any(Number),
+      });
+    });
+
+    it('works with injectable spawn/fetch for testing', () => {
+      const executor = createExecutor({
+        spawn: vi.fn(),
+        fetch: vi.fn(),
+      });
+
+      expect(executor).toBeDefined();
+      expect(executor.execute).toBeDefined();
+    });
+  });
+});

package/server/lib/llm/provider-registry.js

@@ -0,0 +1,104 @@
+/**
+ * Provider Registry
+ *
+ * Runtime registry of available LLM providers with health status.
+ * Tracks which providers are available and routes by capability.
+ *
+ * @module llm/provider-registry
+ */
+
+/**
+ * Create a provider registry
+ * @param {Object} options - Registry options
+ * @param {Function} options.healthCheck - Health check function(provider) → { available, version }
+ * @param {number} options.cacheTTL - Health cache TTL in ms (default 30000)
+ * @returns {Object} Registry instance
+ */
+function createRegistry(options = {}) {
+  const { healthCheck, cacheTTL = 30000 } = options;
+  const providers = new Map();
+  const healthCache = new Map();
+
+  return {
+    /**
+     * Register a provider
+     * @param {Object} provider - Provider config
+     */
+    register(provider) {
+      providers.set(provider.name, { ...provider, status: 'unknown' });
+    },
+
+    /**
+     * List all registered providers
+     * @returns {Array} Provider list
+     */
+    list() {
+      return Array.from(providers.values());
+    },
+
+    /**
+     * Check health of a specific provider
+     * @param {string} name - Provider name
+     * @returns {Promise<Object>} Health status
+     */
+    async checkHealth(name) {
+      const provider = providers.get(name);
+      if (!provider) return { available: false, error: 'unknown provider' };
+
+      // Check cache
+      const cached = healthCache.get(name);
+      if (cached && (Date.now() - cached.timestamp) < cacheTTL) {
+        return cached.status;
+      }
+
+      const status = await healthCheck(provider);
+      provider.status = status.available ? 'available' : 'unavailable';
+
+      healthCache.set(name, { status, timestamp: Date.now() });
+
+      return status;
+    },
+
+    /**
+     * Get providers by capability
+     * @param {string} capability - Capability name (e.g., 'review')
+     * @returns {Array} Matching providers
+     */
+    getByCapability(capability) {
+      return Array.from(providers.values())
+        .filter(p => p.capabilities && p.capabilities.includes(capability));
+    },
+
+    /**
+     * Get best available provider for a capability
+     * @param {string} capability - Capability name
+     * @returns {Promise<Object|null>} Best provider or null
+     */
+    async getBestProvider(capability) {
+      const candidates = this.getByCapability(capability)
+        .sort((a, b) => (a.priority || 99) - (b.priority || 99));
+
+      for (const provider of candidates) {
+        const status = await this.checkHealth(provider.name);
+        if (status.available) return provider;
+      }
+
+      return null;
+    },
+
+    /**
+     * Load providers from config object
+     * @param {Object} config - Config with providers map
+     */
+    loadFromConfig(config) {
+      const providerMap = config.providers || {};
+      for (const [name, providerConfig] of Object.entries(providerMap)) {
+        this.register({ name, ...providerConfig });
+      }
+    },
+  };
+}
+
+module.exports = {
+  createRegistry,
+};