tlc-claude-code 1.8.5 → 2.1.0

package/server/lib/embedding-client.js

@@ -0,0 +1,160 @@
+/**
+ * Embedding Client — Ollama-based text embedding with graceful degradation.
+ *
+ * Generates vector embeddings from text using a local Ollama instance.
+ * Returns null when Ollama is unavailable (caller falls back to text search).
+ *
+ * @module embedding-client
+ */
+
+/** Max characters to send per embed request (~8192 tokens * 4 chars/token) */
+const MAX_INPUT_CHARS = 32768;
+
+/** Known model dimensions */
+const MODEL_DIMENSIONS = {
+  'mxbai-embed-large': 1024,
+  'nomic-embed-text': 768,
+  'all-minilm': 384,
+};
+
+/**
+ * Create an embedding client that talks to Ollama.
+ *
+ * @param {object} [options]
+ * @param {string} [options.host='http://localhost:11434'] - Ollama host URL
+ * @param {string} [options.model='mxbai-embed-large'] - Embedding model name
+ * @param {number} [options.timeout=30000] - Request timeout in ms
+ * @returns {object} Client with embed/embedBatch/isAvailable/getModelInfo
+ */
+export function createEmbeddingClient(options = {}) {
+  const host = options.host || 'http://localhost:11434';
+  const model = options.model || 'mxbai-embed-large';
+  const timeout = options.timeout || 30000;
+
+  /**
+   * Truncate text to fit within model token limits.
+   */
+  function truncateText(text) {
+    if (text.length > MAX_INPUT_CHARS) {
+      return text.slice(0, MAX_INPUT_CHARS);
+    }
+    return text;
+  }
+
+  /**
+   * Embed a single text string.
+   * @param {string} text
+   * @returns {Promise<Float32Array|null>} Embedding or null if unavailable
+   */
+  async function embed(text) {
+    if (!text || text.length === 0) {
+      return null;
+    }
+
+    try {
+      const input = truncateText(text);
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      const response = await fetch(`${host}/api/embed`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model, input }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        return null;
+      }
+
+      const data = await response.json();
+      if (!data.embeddings || data.embeddings.length === 0) {
+        return null;
+      }
+
+      return new Float32Array(data.embeddings[0]);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Embed multiple texts in a single batch request.
+   * @param {string[]} texts
+   * @returns {Promise<(Float32Array|null)[]>}
+   */
+  async function embedBatch(texts) {
+    if (!texts || texts.length === 0) {
+      return [];
+    }
+
+    try {
+      const inputs = texts.map(truncateText);
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      const response = await fetch(`${host}/api/embed`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model, input: inputs }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        return texts.map(() => null);
+      }
+
+      const data = await response.json();
+      if (!data.embeddings) {
+        return texts.map(() => null);
+      }
+
+      return data.embeddings.map((emb) => new Float32Array(emb));
+    } catch {
+      return texts.map(() => null);
+    }
+  }
+
+  /**
+   * Check if Ollama is running and accessible.
+   * @returns {Promise<boolean>}
+   */
+  async function isAvailable() {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+      const response = await fetch(`${host}/api/tags`, {
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get info about the configured embedding model.
+   * @returns {{ model: string, dimensions: number }}
+   */
+  function getModelInfo() {
+    return {
+      model,
+      dimensions: MODEL_DIMENSIONS[model] || 1024,
+    };
+  }
+
+  return {
+    embed,
+    embedBatch,
+    isAvailable,
+    getModelInfo,
+  };
+}

package/server/lib/embedding-client.test.js

@@ -0,0 +1,243 @@
+/**
+ * Embedding Client Tests
+ * Tests for Ollama-based embedding client with graceful degradation
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createEmbeddingClient } from './embedding-client.js';
+
+describe('embedding-client', () => {
+  let client;
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    global.fetch = vi.fn();
+    client = createEmbeddingClient();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  describe('embed', () => {
+    it('embeds text and returns Float32Array', async () => {
+      const mockEmbedding = Array.from({ length: 1024 }, (_, i) => i * 0.001);
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding],
+        }),
+      });
+
+      const result = await client.embed('hello world');
+
+      expect(result).toBeInstanceOf(Float32Array);
+      expect(global.fetch).toHaveBeenCalledWith(
+        'http://localhost:11434/api/embed',
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.any(String),
+        })
+      );
+
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+      expect(body.model).toBe('mxbai-embed-large');
+      expect(body.input).toBe('hello world');
+    });
+
+    it('returns correct dimensions for mxbai-embed-large (1024)', async () => {
+      const mockEmbedding = Array.from({ length: 1024 }, () => Math.random());
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding],
+        }),
+      });
+
+      const result = await client.embed('test text');
+
+      expect(result).toBeInstanceOf(Float32Array);
+      expect(result.length).toBe(1024);
+    });
+
+    it('returns null on connection failure (graceful degradation)', async () => {
+      global.fetch = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+
+      const result = await client.embed('some text');
+
+      expect(result).toBeNull();
+    });
+
+    it('returns null for empty text', async () => {
+      const result = await client.embed('');
+
+      expect(result).toBeNull();
+      expect(global.fetch).not.toHaveBeenCalled();
+    });
+
+    it('truncates text exceeding token limit (8192 tokens ~ 32768 chars)', async () => {
+      const longText = 'a'.repeat(40000);
+      const mockEmbedding = Array.from({ length: 1024 }, () => 0.5);
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding],
+        }),
+      });
+
+      await client.embed(longText);
+
+      expect(global.fetch).toHaveBeenCalled();
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+      expect(body.input.length).toBeLessThanOrEqual(32768);
+    });
+
+    it('handles Ollama API error responses', async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        json: () => Promise.resolve({ error: 'model not found' }),
+      });
+
+      const result = await client.embed('test');
+
+      expect(result).toBeNull();
+    });
+
+    it('times out after 30s default', async () => {
+      global.fetch = vi.fn().mockImplementation((url, opts) => {
+        // Verify that an AbortSignal is passed for timeout control
+        expect(opts.signal).toBeDefined();
+        return new Promise((_, reject) => {
+          const error = new Error('The operation was aborted');
+          error.name = 'AbortError';
+          reject(error);
+        });
+      });
+
+      const result = await client.embed('test');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('embedBatch', () => {
+    it('batch embed processes multiple texts', async () => {
+      const mockEmbedding1 = Array.from({ length: 1024 }, () => 0.1);
+      const mockEmbedding2 = Array.from({ length: 1024 }, () => 0.2);
+      const mockEmbedding3 = Array.from({ length: 1024 }, () => 0.3);
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding1, mockEmbedding2, mockEmbedding3],
+        }),
+      });
+
+      const results = await client.embedBatch(['text one', 'text two', 'text three']);
+
+      expect(results).toHaveLength(3);
+    });
+
+    it('batch embed returns array of Float32Arrays', async () => {
+      const mockEmbedding1 = Array.from({ length: 1024 }, () => 0.1);
+      const mockEmbedding2 = Array.from({ length: 1024 }, () => 0.2);
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding1, mockEmbedding2],
+        }),
+      });
+
+      const results = await client.embedBatch(['hello', 'world']);
+
+      expect(results).toHaveLength(2);
+      results.forEach(result => {
+        expect(result).toBeInstanceOf(Float32Array);
+        expect(result.length).toBe(1024);
+      });
+    });
+  });
+
+  describe('isAvailable', () => {
+    it('returns true when Ollama is running', async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          models: [{ name: 'mxbai-embed-large', size: 670000000 }],
+        }),
+      });
+
+      const available = await client.isAvailable();
+
+      expect(available).toBe(true);
+      expect(global.fetch).toHaveBeenCalledWith(
+        'http://localhost:11434/api/tags',
+        expect.any(Object)
+      );
+    });
+
+    it('returns false when Ollama is not running', async () => {
+      global.fetch = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+
+      const available = await client.isAvailable();
+
+      expect(available).toBe(false);
+    });
+  });
+
+  describe('getModelInfo', () => {
+    it('returns model name and dimensions', () => {
+      const info = client.getModelInfo();
+
+      expect(info).toEqual({
+        model: 'mxbai-embed-large',
+        dimensions: 1024,
+      });
+    });
+  });
+
+  describe('configuration', () => {
+    it('respects configurable model name', async () => {
+      const customClient = createEmbeddingClient({ model: 'nomic-embed-text' });
+      const mockEmbedding = Array.from({ length: 768 }, () => 0.5);
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding],
+        }),
+      });
+
+      await customClient.embed('test');
+
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+      expect(body.model).toBe('nomic-embed-text');
+    });
+
+    it('respects configurable host', async () => {
+      const customClient = createEmbeddingClient({ host: 'http://ollama.local:11434' });
+      const mockEmbedding = Array.from({ length: 1024 }, () => 0.5);
+
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          embeddings: [mockEmbedding],
+        }),
+      });
+
+      await customClient.embed('test');
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        'http://ollama.local:11434/api/embed',
+        expect.any(Object)
+      );
+    });
+  });
+});

package/server/lib/global-config.js

@@ -0,0 +1,198 @@
+/**
+ * Global TLC Configuration - Persistent config at ~/.tlc/config.json
+ *
+ * Stores workspace root paths and settings that survive reinstalls.
+ * XDG-aware: uses $TLC_CONFIG_DIR or defaults to ~/.tlc/
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_FILENAME = 'config.json';
+
+/**
+ * Get the config directory path
+ * @returns {string}
+ */
+function getConfigDir() {
+  if (process.env.TLC_CONFIG_DIR) {
+    return process.env.TLC_CONFIG_DIR;
+  }
+  return path.join(os.homedir(), '.tlc');
+}
+
+/**
+ * Default config structure
+ * @returns {object}
+ */
+function defaultConfig() {
+  return {
+    version: 1,
+    roots: [],
+    scanDepth: 5,
+    lastScans: {},
+  };
+}
+
+class GlobalConfig {
+  constructor() {
+    this.configDir = getConfigDir();
+    this.configPath = path.join(this.configDir, CONFIG_FILENAME);
+    this._config = null;
+  }
+
+  /**
+   * Load config from disk, creating defaults if needed
+   * @returns {object} The config object
+   */
+  load() {
+    this._ensureDir();
+
+    if (fs.existsSync(this.configPath)) {
+      try {
+        const raw = fs.readFileSync(this.configPath, 'utf-8');
+        this._config = JSON.parse(raw);
+        return this._config;
+      } catch (err) {
+        // Corrupted JSON — reset to defaults
+        console.error('Corrupted config, resetting to defaults:', err.message);
+        this._config = defaultConfig();
+        this._save();
+        return this._config;
+      }
+    }
+
+    // First access — create defaults
+    this._config = defaultConfig();
+    this._save();
+    return this._config;
+  }
+
+  /**
+   * Get all configured root paths
+   * @returns {string[]}
+   */
+  getRoots() {
+    this._ensureLoaded();
+    return [...this._config.roots];
+  }
+
+  /**
+   * Add a root directory path
+   * @param {string} rootPath - Absolute path to a directory
+   * @throws {Error} If path is invalid
+   */
+  addRoot(rootPath) {
+    this._ensureLoaded();
+
+    const resolved = path.resolve(rootPath);
+
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Path does not exist: ${resolved}`);
+    }
+
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+      throw new Error(`Path is not a directory: ${resolved}`);
+    }
+
+    if (this._config.roots.includes(resolved)) {
+      throw new Error(`Root already configured: ${resolved}`);
+    }
+
+    this._config.roots.push(resolved);
+    this._save();
+  }
+
+  /**
+   * Remove a root directory path
+   * @param {string} rootPath - Path to remove
+   */
+  removeRoot(rootPath) {
+    this._ensureLoaded();
+
+    const resolved = path.resolve(rootPath);
+    this._config.roots = this._config.roots.filter((r) => r !== resolved);
+
+    // Clean up lastScans entry
+    delete this._config.lastScans[resolved];
+
+    this._save();
+  }
+
+  /**
+   * Check if any roots are configured
+   * @returns {boolean}
+   */
+  isConfigured() {
+    this._ensureLoaded();
+    return this._config.roots.length > 0;
+  }
+
+  /**
+   * Set scan depth
+   * @param {number} depth
+   */
+  setScanDepth(depth) {
+    this._ensureLoaded();
+    this._config.scanDepth = depth;
+    this._save();
+  }
+
+  /**
+   * Set last scan timestamp for a root
+   * @param {string} rootPath
+   * @param {number} timestamp
+   */
+  setLastScan(rootPath, timestamp) {
+    this._ensureLoaded();
+    const resolved = path.resolve(rootPath);
+    this._config.lastScans[resolved] = timestamp;
+    this._save();
+  }
+
+  /**
+   * Get last scan timestamp for a root
+   * @param {string} rootPath
+   * @returns {number|null}
+   */
+  getLastScan(rootPath) {
+    this._ensureLoaded();
+    const resolved = path.resolve(rootPath);
+    return this._config.lastScans[resolved] || null;
+  }
+
+  /**
+   * Ensure config directory exists
+   * @private
+   */
+  _ensureDir() {
+    if (!fs.existsSync(this.configDir)) {
+      fs.mkdirSync(this.configDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Ensure config is loaded
+   * @private
+   */
+  _ensureLoaded() {
+    if (!this._config) {
+      this.load();
+    }
+  }
+
+  /**
+   * Atomic write to config file
+   * @private
+   */
+  _save() {
+    this._ensureDir();
+    const tmpPath = this.configPath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(this._config, null, 2), 'utf-8');
+    fs.renameSync(tmpPath, this.configPath);
+  }
+}
+
+module.exports = { GlobalConfig };