bluera-knowledge 0.9.32 → 0.9.36

package/src/services/services.test.ts

@@ -62,7 +62,7 @@ describe('destroyServices', () => {
   it('waits for LanceStore async cleanup before returning', async () => {
     let closeCompleted = false;
     mockLance.closeAsync.mockImplementation(async () => {
-      await new Promise(resolve => setTimeout(resolve, 50));
+      await new Promise((resolve) => setTimeout(resolve, 50));
       closeCompleted = true;
     });
 

package/src/services/snippet.service.test.ts

@@ -24,7 +24,8 @@ describe('SnippetService', () => {
     });
 
     it('extracts snippet around single query term match', () => {
-      const content = 'The quick brown fox jumps over the lazy dog. ' +
+      const content =
+        'The quick brown fox jumps over the lazy dog. ' +
         'This is some filler text to make the content longer. ' +
         'Here is the important keyword we want to find. ' +
         'More filler text at the end to extend the content.';
@@ -34,7 +35,8 @@ describe('SnippetService', () => {
     });
 
     it('extracts snippet around multiple clustered query terms', () => {
-      const content = 'Unrelated text at the start. '.repeat(10) +
+      const content =
+        'Unrelated text at the start. '.repeat(10) +
         'Here is the target area with multiple keywords: search query terms matching. ' +
         'Unrelated text at the end. '.repeat(10);
       const snippet = extractSnippet(content, 'target keywords search');
@@ -115,7 +117,8 @@ describe('SnippetService', () => {
     });
 
     it('finds best position when multiple query terms appear', () => {
-      const content = 'First occurrence of term. ' +
+      const content =
+        'First occurrence of term. ' +
         'A'.repeat(200) +
         ' Second occurrence with more terms from query nearby. ' +
         'A'.repeat(200);
@@ -139,7 +142,9 @@ describe('SnippetService', () => {
 
     it('calculates proximity score correctly', () => {
       // Create content where terms are closer together in one location
-      const content = 'distant word here. ' + 'A'.repeat(300) +
+      const content =
+        'distant word here. ' +
+        'A'.repeat(300) +
         ' clustered search query terms all together here ' +
         'A'.repeat(300);
       const snippet = extractSnippet(content, 'search query terms', { maxLength: 100 });
@@ -186,11 +191,14 @@ describe('SnippetService', () => {
     });
 
     it('scores positions based on unique nearby terms', () => {
-      const content = 'repeated repeated repeated. ' +
+      const content =
+        'repeated repeated repeated. ' +
         'A'.repeat(100) +
         ' diverse unique different varied terms here ' +
         'A'.repeat(100);
-      const snippet = extractSnippet(content, 'diverse unique different varied', { maxLength: 100 });
+      const snippet = extractSnippet(content, 'diverse unique different varied', {
+        maxLength: 100,
+      });
       expect(snippet).toContain('diverse');
       expect(snippet).toContain('unique');
     });

package/src/services/snippet.service.ts

@@ -30,7 +30,7 @@ export function extractSnippet(
   const queryTerms = query
     .toLowerCase()
     .split(/\s+/)
-    .filter(t => t.length > 2); // Skip very short words
+    .filter((t) => t.length > 2); // Skip very short words
 
   // Normalize content for extraction
   const normalizedContent = content.replace(/\s+/g, ' ').trim();
@@ -112,7 +112,9 @@ function findBestMatchPosition(content: string, queryTerms: string[]): number {
     }
 
     // Bonus: Near markdown section header
-    const headerMatch = content.slice(Math.max(0, position - 100), position).match(/^#{1,3}\s+.+$/m);
+    const headerMatch = content
+      .slice(Math.max(0, position - 100), position)
+      .match(/^#{1,3}\s+.+$/m);
     if (headerMatch) {
       score += 4;
     }
@@ -166,10 +168,10 @@ function extractContextWindow(
 
   // Add ellipsis indicators
   if (start > 0) {
-    snippet = '...' + snippet;
+    snippet = `...${snippet}`;
   }
   if (end < content.length) {
-    snippet = snippet + '...';
+    snippet = `${snippet}...`;
   }
 
   return snippet;
@@ -187,5 +189,5 @@ function truncateWithEllipsis(content: string, maxLength: number): string {
   const truncateAt = content.lastIndexOf(' ', maxLength - 3);
   const cutPoint = truncateAt > maxLength * 0.5 ? truncateAt : maxLength - 3;
 
-  return content.slice(0, cutPoint).trim() + '...';
+  return `${content.slice(0, cutPoint).trim()}...`;
 }

package/src/services/store.service.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { StoreService } from './store.service.js';
-import { rm, mkdtemp } from 'node:fs/promises';
+import { rm, mkdtemp, writeFile, access } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -91,7 +91,7 @@ describe('StoreService', () => {
         name: 'Described Files',
         type: 'file',
         path: tempDir,
-        description: 'My file collection'
+        description: 'My file collection',
       });
 
       expect(result.success).toBe(true);
@@ -105,7 +105,7 @@ describe('StoreService', () => {
         name: 'Tagged Files',
         type: 'file',
         path: tempDir,
-        tags: ['important', 'work']
+        tags: ['important', 'work'],
       });
 
       expect(result.success).toBe(true);
@@ -117,7 +117,7 @@ describe('StoreService', () => {
     it('returns error when path not provided for file store', async () => {
       const result = await storeService.create({
         name: 'No Path',
-        type: 'file'
+        type: 'file',
       });
 
       expect(result.success).toBe(false);
@@ -130,7 +130,7 @@ describe('StoreService', () => {
       const result = await storeService.create({
         name: 'Bad Path',
         type: 'file',
-        path: '/nonexistent/path'
+        path: '/nonexistent/path',
       });
 
       expect(result.success).toBe(false);
@@ -145,7 +145,7 @@ describe('StoreService', () => {
       const result = await storeService.create({
         name: 'My Repo',
         type: 'repo',
-        path: tempDir
+        path: tempDir,
       });
 
       expect(result.success).toBe(true);
@@ -160,7 +160,7 @@ describe('StoreService', () => {
         name: 'Branched Repo',
         type: 'repo',
         path: tempDir,
-        branch: 'develop'
+        branch: 'develop',
       });
 
       expect(result.success).toBe(true);
@@ -172,7 +172,7 @@ describe('StoreService', () => {
     it('returns error when neither path nor URL provided for repo', async () => {
       const result = await storeService.create({
         name: 'No Path No URL',
-        type: 'repo'
+        type: 'repo',
       });
 
       expect(result.success).toBe(false);
@@ -187,7 +187,7 @@ describe('StoreService', () => {
       const result = await storeService.create({
         name: 'My Website',
         type: 'web',
-        url: 'https://example.com'
+        url: 'https://example.com',
       });
 
       expect(result.success).toBe(true);
@@ -202,7 +202,7 @@ describe('StoreService', () => {
         name: 'Deep Site',
         type: 'web',
         url: 'https://example.com',
-        depth: 3
+        depth: 3,
       });
 
       expect(result.success).toBe(true);
@@ -215,7 +215,7 @@ describe('StoreService', () => {
       const result = await storeService.create({
         name: 'Default Depth',
         type: 'web',
-        url: 'https://example.com'
+        url: 'https://example.com',
       });
 
       expect(result.success).toBe(true);
@@ -227,7 +227,7 @@ describe('StoreService', () => {
     it('returns error when URL not provided for web store', async () => {
       const result = await storeService.create({
         name: 'No URL',
-        type: 'web'
+        type: 'web',
       });
 
       expect(result.success).toBe(false);
@@ -242,7 +242,7 @@ describe('StoreService', () => {
       const result = await storeService.create({
         name: '',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       expect(result.success).toBe(false);
@@ -255,7 +255,7 @@ describe('StoreService', () => {
       const result = await storeService.create({
         name: '   ',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       expect(result.success).toBe(false);
@@ -273,13 +273,13 @@ describe('StoreService', () => {
       await storeService.create({
         name: 'Duplicate',
         type: 'file',
-        path: dir1
+        path: dir1,
       });
 
       const result = await storeService.create({
         name: 'Duplicate',
         type: 'file',
-        path: dir2
+        path: dir2,
       });
 
       expect(result.success).toBe(false);
@@ -344,7 +344,7 @@ describe('StoreService', () => {
       const createResult = await storeService.create({
         name: 'Test Store',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       if (!createResult.success) throw new Error('Create failed');
@@ -357,7 +357,7 @@ describe('StoreService', () => {
       await storeService.create({
         name: 'Test Store',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       const store = await storeService.getByIdOrName('Test Store');
@@ -375,13 +375,13 @@ describe('StoreService', () => {
       const createResult = await storeService.create({
         name: 'Original Name',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       if (!createResult.success) throw new Error('Create failed');
 
       const updateResult = await storeService.update(createResult.data.id, {
-        name: 'Updated Name'
+        name: 'Updated Name',
       });
 
       expect(updateResult.success).toBe(true);
@@ -394,13 +394,13 @@ describe('StoreService', () => {
       const createResult = await storeService.create({
         name: 'Test Store',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       if (!createResult.success) throw new Error('Create failed');
 
       const updateResult = await storeService.update(createResult.data.id, {
-        description: 'New description'
+        description: 'New description',
       });
 
       expect(updateResult.success).toBe(true);
@@ -413,13 +413,13 @@ describe('StoreService', () => {
       const createResult = await storeService.create({
         name: 'Test Store',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       if (!createResult.success) throw new Error('Create failed');
 
       const updateResult = await storeService.update(createResult.data.id, {
-        tags: ['new', 'tags']
+        tags: ['new', 'tags'],
       });
 
       expect(updateResult.success).toBe(true);
@@ -432,17 +432,17 @@ describe('StoreService', () => {
       const createResult = await storeService.create({
         name: 'Test Store',
         type: 'file',
-        path: tempDir
+        path: tempDir,
       });
 
       if (!createResult.success) throw new Error('Create failed');
       const originalUpdatedAt = createResult.data.updatedAt;
 
       // Wait a bit to ensure timestamp is different
-      await new Promise(resolve => setTimeout(resolve, 10));
+      await new Promise((resolve) => setTimeout(resolve, 10));
 
       const updateResult = await storeService.update(createResult.data.id, {
-        name: 'Updated'
+        name: 'Updated',
       });
 
       expect(updateResult.success).toBe(true);
@@ -453,7 +453,7 @@ describe('StoreService', () => {
 
     it('returns error when updating nonexistent store', async () => {
       const result = await storeService.update('nonexistent-id' as any, {
-        name: 'Updated'
+        name: 'Updated',
       });
 
       expect(result.success).toBe(false);
@@ -480,7 +480,7 @@ describe('StoreService', () => {
       await storeService.create({
         name: 'Persistent Store',
         type: 'file',
-        path: storeDir
+        path: storeDir,
       });
 
       // Create new service instance with same data dir
@@ -499,4 +499,43 @@ describe('StoreService', () => {
       expect(stores).toHaveLength(0);
     });
   });
+
+  describe('first-run vs corruption handling (CLAUDE.md compliance)', () => {
+    it('creates stores.json file on first run', async () => {
+      const freshDir = await mkdtemp(join(tmpdir(), 'fresh-'));
+      const freshService = new StoreService(freshDir);
+      await freshService.initialize();
+
+      // File should now exist
+      const registryPath = join(freshDir, 'stores.json');
+      await expect(access(registryPath)).resolves.toBeUndefined();
+
+      await rm(freshDir, { recursive: true, force: true });
+    });
+
+    it('throws on corrupted stores.json', async () => {
+      const corruptDir = await mkdtemp(join(tmpdir(), 'corrupt-'));
+      const registryPath = join(corruptDir, 'stores.json');
+      await writeFile(registryPath, '{invalid json syntax');
+
+      const freshService = new StoreService(corruptDir);
+
+      // Should throw per CLAUDE.md "fail early and fast"
+      await expect(freshService.initialize()).rejects.toThrow();
+
+      await rm(corruptDir, { recursive: true, force: true });
+    });
+
+    it('throws with descriptive message on JSON parse error', async () => {
+      const corruptDir = await mkdtemp(join(tmpdir(), 'corrupt-'));
+      const registryPath = join(corruptDir, 'stores.json');
+      await writeFile(registryPath, '{"stores": [');
+
+      const freshService = new StoreService(corruptDir);
+
+      await expect(freshService.initialize()).rejects.toThrow(/JSON|parse|registry/i);
+
+      await rm(corruptDir, { recursive: true, force: true });
+    });
+  });
 });

package/src/services/store.service.ts

@@ -1,12 +1,24 @@
-import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import type { Store, FileStore, RepoStore, WebStore, StoreType } from '../types/store.js';
-import type { StoreId } from '../types/brands.js';
+import { readFile, writeFile, mkdir, stat, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cloneRepository } from '../plugin/git-clone.js';
 import { createStoreId } from '../types/brands.js';
-import type { Result } from '../types/result.js';
 import { ok, err } from '../types/result.js';
-import { cloneRepository } from '../plugin/git-clone.js';
+import type { StoreId } from '../types/brands.js';
+import type { Result } from '../types/result.js';
+import type { Store, FileStore, RepoStore, WebStore, StoreType } from '../types/store.js';
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 export interface CreateStoreInput {
   name: string;
@@ -91,7 +103,7 @@ export class StoreService {
             url: input.url,
             targetDir: cloneDir,
             ...(input.branch !== undefined ? { branch: input.branch } : {}),
-            depth: input.depth ?? 1
+            depth: input.depth ?? 1,
           });
 
           if (!result.success) {
@@ -164,10 +176,15 @@ export class StoreService {
   }
 
   async getByIdOrName(idOrName: string): Promise<Store | undefined> {
-    return Promise.resolve(this.registry.stores.find((s) => s.id === idOrName || s.name === idOrName));
+    return Promise.resolve(
+      this.registry.stores.find((s) => s.id === idOrName || s.name === idOrName)
+    );
   }
 
-  async update(id: StoreId, updates: Partial<Pick<Store, 'name' | 'description' | 'tags'>>): Promise<Result<Store>> {
+  async update(
+    id: StoreId,
+    updates: Partial<Pick<Store, 'name' | 'description' | 'tags'>>
+  ): Promise<Result<Store>> {
     const index = this.registry.stores.findIndex((s) => s.id === id);
     if (index === -1) {
       return err(new Error(`Store not found: ${id}`));
@@ -205,8 +222,18 @@ export class StoreService {
 
   private async loadRegistry(): Promise<void> {
     const registryPath = join(this.dataDir, 'stores.json');
+    const exists = await fileExists(registryPath);
+
+    if (!exists) {
+      // First run - create empty registry
+      this.registry = { stores: [] };
+      await this.saveRegistry();
+      return;
+    }
+
+    // File exists - load it (throws on corruption per CLAUDE.md "fail early")
+    const content = await readFile(registryPath, 'utf-8');
     try {
-      const content = await readFile(registryPath, 'utf-8');
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
       const data = JSON.parse(content) as { stores: Store[] };
       this.registry = {
@@ -217,8 +244,10 @@ export class StoreService {
           updatedAt: new Date(s.updatedAt),
         })),
       };
-    } catch {
-      this.registry = { stores: [] };
+    } catch (error) {
+      throw new Error(
+        `Failed to parse store registry at ${registryPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
 

package/src/services/watch.service.test.ts

@@ -80,11 +80,14 @@ describe('WatchService', () => {
 
       await watchService.watch(mockFileStore);
 
-      expect(watch).toHaveBeenCalledWith(mockFileStore.path, expect.objectContaining({
-        ignored: expect.any(RegExp),
-        persistent: true,
-        ignoreInitial: true,
-      }));
+      expect(watch).toHaveBeenCalledWith(
+        mockFileStore.path,
+        expect.objectContaining({
+          ignored: expect.any(RegExp),
+          persistent: true,
+          ignoreInitial: true,
+        })
+      );
     });
 
     it('starts watching a repo store', async () => {
@@ -343,10 +346,7 @@ describe('WatchService', () => {
       vi.advanceTimersByTime(1100);
       await vi.runAllTimersAsync();
 
-      expect(consoleErrorSpy).toHaveBeenCalledWith(
-        'Error during reindexing:',
-        expect.any(Error)
-      );
+      expect(consoleErrorSpy).toHaveBeenCalledWith('Error during reindexing:', expect.any(Error));
 
       consoleErrorSpy.mockRestore();
     });
@@ -367,10 +367,7 @@ describe('WatchService', () => {
       vi.advanceTimersByTime(1100);
       await vi.runAllTimersAsync();
 
-      expect(consoleErrorSpy).toHaveBeenCalledWith(
-        'Error during reindexing:',
-        expect.any(Error)
-      );
+      expect(consoleErrorSpy).toHaveBeenCalledWith('Error during reindexing:', expect.any(Error));
 
       consoleErrorSpy.mockRestore();
     });
@@ -397,7 +394,8 @@ describe('WatchService', () => {
       const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
       // First call fails
-      mockIndexService.indexStore = vi.fn()
+      mockIndexService.indexStore = vi
+        .fn()
         .mockRejectedValueOnce(new Error('First fail'))
         .mockResolvedValueOnce({ ok: true });
 
@@ -464,6 +462,28 @@ describe('WatchService', () => {
       expect(watcher1?.close).toHaveBeenCalled();
       expect(watcher2?.close).not.toHaveBeenCalled();
     });
+
+    it('clears pending timeout to prevent timer leak', async () => {
+      await watchService.watch(mockFileStore, 1000);
+
+      const watcher = mockWatchers[0];
+      const allHandler = (watcher?.on as ReturnType<typeof vi.fn>).mock.calls.find(
+        (call: unknown[]) => call[0] === 'all'
+      )?.[1] as (() => void) | undefined;
+
+      // Trigger a file change (sets timeout)
+      allHandler?.();
+
+      // Unwatch before timeout fires
+      await watchService.unwatch(mockFileStore.id);
+
+      // Advance past debounce time - timeout should NOT fire
+      vi.advanceTimersByTime(1500);
+      await vi.runAllTimersAsync();
+
+      // indexStore should NOT have been called since we unwatched
+      expect(mockIndexService.indexStore).not.toHaveBeenCalled();
+    });
   });
 
   describe('unwatchAll', () => {

package/src/services/watch.service.ts

@@ -1,10 +1,11 @@
 import { watch, type FSWatcher } from 'chokidar';
-import type { FileStore, RepoStore } from '../types/store.js';
 import type { IndexService } from './index.service.js';
 import type { LanceStore } from '../db/lance.js';
+import type { FileStore, RepoStore } from '../types/store.js';
 
 export class WatchService {
   private readonly watchers: Map<string, FSWatcher> = new Map();
+  private readonly pendingTimeouts: Map<string, NodeJS.Timeout> = new Map();
   private readonly indexService: IndexService;
   private readonly lanceStore: LanceStore;
 
@@ -33,6 +34,7 @@ export class WatchService {
     const reindexHandler = (): void => {
       if (timeout) clearTimeout(timeout);
       timeout = setTimeout(() => {
+        this.pendingTimeouts.delete(store.id);
         void (async (): Promise<void> => {
           try {
             await this.lanceStore.initialize(store.id);
@@ -43,6 +45,7 @@ export class WatchService {
           }
         })();
       }, debounceMs);
+      this.pendingTimeouts.set(store.id, timeout);
     };
 
     watcher.on('all', reindexHandler);
@@ -56,6 +59,13 @@ export class WatchService {
   }
 
   async unwatch(storeId: string): Promise<void> {
+    // Clear any pending timeout to prevent timer leak
+    const pendingTimeout = this.pendingTimeouts.get(storeId);
+    if (pendingTimeout) {
+      clearTimeout(pendingTimeout);
+      this.pendingTimeouts.delete(storeId);
+    }
+
     const watcher = this.watchers.get(storeId);
     if (watcher) {
       await watcher.close();

package/src/types/brands.test.ts

@@ -15,7 +15,9 @@ describe('branded types', () => {
     });
 
     it('throws error for invalid store ID', () => {
-      expect(() => createStoreId('invalid id with spaces')).toThrow('Invalid store ID: invalid id with spaces');
+      expect(() => createStoreId('invalid id with spaces')).toThrow(
+        'Invalid store ID: invalid id with spaces'
+      );
     });
 
     it('throws error for empty store ID', () => {

package/src/types/index.ts

@@ -9,15 +9,7 @@ export {
 } from './brands.js';
 
 // Result type
-export {
-  type Result,
-  ok,
-  err,
-  isOk,
-  isErr,
-  unwrap,
-  unwrapOr,
-} from './result.js';
+export { type Result, ok, err, isOk, isErr, unwrap, unwrapOr } from './result.js';
 
 // Store types
 export {
@@ -60,7 +52,4 @@ export {
 } from './config.js';
 
 // Progress types
-export {
-  type ProgressEvent,
-  type ProgressCallback,
-} from './progress.js';
+export { type ProgressEvent, type ProgressCallback } from './progress.js';

package/src/types/search.ts

@@ -75,14 +75,16 @@ export interface SearchResult {
   readonly full?: ResultFull | undefined;
 
   // Ranking attribution metadata for transparency
-  readonly rankingMetadata?: {
-    readonly vectorRank?: number;    // Position in vector results (1-based)
-    readonly ftsRank?: number;       // Position in FTS results (1-based)
-    readonly vectorRRF: number;      // Vector contribution to RRF score
-    readonly ftsRRF: number;         // FTS contribution to RRF score
-    readonly fileTypeBoost: number;  // File type multiplier applied
-    readonly frameworkBoost: number; // Framework context multiplier
-  } | undefined;
+  readonly rankingMetadata?:
+    | {
+        readonly vectorRank?: number; // Position in vector results (1-based)
+        readonly ftsRank?: number; // Position in FTS results (1-based)
+        readonly vectorRRF: number; // Vector contribution to RRF score
+        readonly ftsRRF: number; // FTS contribution to RRF score
+        readonly fileTypeBoost: number; // File type multiplier applied
+        readonly frameworkBoost: number; // Framework context multiplier
+      }
+    | undefined;
 }
 
 export interface SearchResponse {