bluera-knowledge 0.9.21

package/src/mcp/handlers/job.handler.ts

@@ -0,0 +1,116 @@
+import type { ToolHandler, ToolResponse } from '../types.js';
+import type {
+  CheckJobStatusArgs,
+  ListJobsArgs,
+  CancelJobArgs
+} from '../schemas/index.js';
+import {
+  CheckJobStatusArgsSchema,
+  ListJobsArgsSchema,
+  CancelJobArgsSchema
+} from '../schemas/index.js';
+import { JobService } from '../../services/job.service.js';
+
+/**
+ * Handle check_job_status requests
+ *
+ * Retrieves the current status of a background job.
+ */
+export const handleCheckJobStatus: ToolHandler<CheckJobStatusArgs> = (
+  args,
+  context
+): Promise<ToolResponse> => {
+  // Validate arguments with Zod
+  const validated = CheckJobStatusArgsSchema.parse(args);
+
+  const { options } = context;
+
+  const jobService = new JobService(options.dataDir);
+  const job = jobService.getJob(validated.jobId);
+
+  if (!job) {
+    throw new Error(`Job not found: ${validated.jobId}`);
+  }
+
+  return Promise.resolve({
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(job, null, 2)
+      }
+    ]
+  });
+};
+
+/**
+ * Handle list_jobs requests
+ *
+ * Lists all jobs with optional filtering by status or active status.
+ */
+export const handleListJobs: ToolHandler<ListJobsArgs> = (
+  args,
+  context
+): Promise<ToolResponse> => {
+  // Validate arguments with Zod
+  const validated = ListJobsArgsSchema.parse(args);
+
+  const { options } = context;
+
+  const jobService = new JobService(options.dataDir);
+
+  let jobs;
+  if (validated.activeOnly === true) {
+    jobs = jobService.listActiveJobs();
+  } else if (validated.status !== undefined) {
+    jobs = jobService.listJobs(validated.status);
+  } else {
+    jobs = jobService.listJobs();
+  }
+
+  return Promise.resolve({
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({ jobs }, null, 2)
+      }
+    ]
+  });
+};
+
+/**
+ * Handle cancel_job requests
+ *
+ * Cancels a running or pending background job.
+ * Kills the worker process if it exists.
+ */
+export const handleCancelJob: ToolHandler<CancelJobArgs> = (
+  args,
+  context
+): Promise<ToolResponse> => {
+  // Validate arguments with Zod
+  const validated = CancelJobArgsSchema.parse(args);
+
+  const { options } = context;
+
+  const jobService = new JobService(options.dataDir);
+  const result = jobService.cancelJob(validated.jobId);
+
+  if (!result.success) {
+    throw new Error(result.error.message);
+  }
+
+  const job = jobService.getJob(validated.jobId);
+
+  return Promise.resolve({
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({
+          success: true,
+          job,
+          message: 'Job cancelled successfully'
+        }, null, 2)
+      }
+    ]
+  });
+};

package/src/mcp/handlers/search.handler.test.ts

@@ -0,0 +1,334 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { handleSearch, handleGetFullContext, resultCache } from './search.handler.js';
+import type { HandlerContext } from '../types.js';
+import type { ServiceContainer } from '../../services/index.js';
+
+describe('Search Handlers', () => {
+  let mockContext: HandlerContext;
+  let mockServices: ServiceContainer;
+
+  beforeEach(() => {
+    // Clear result cache before each test
+    resultCache.clear();
+
+    // Create mock services
+    mockServices = {
+      store: {
+        list: vi.fn().mockResolvedValue([
+          { id: 'store1', name: 'Test Store', type: 'file' }
+        ]),
+        getByIdOrName: vi.fn().mockResolvedValue({
+          id: 'store1',
+          name: 'Test Store',
+          type: 'file',
+          path: '/test/path'
+        })
+      },
+      lance: {
+        initialize: vi.fn().mockResolvedValue(undefined)
+      },
+      search: {
+        search: vi.fn().mockResolvedValue({
+          results: [
+            {
+              id: 'doc1',
+              score: 0.95,
+              content: 'test content for search',
+              metadata: { storeId: 'store1' },
+              summary: { file: 'test.ts', line: 1 }
+            }
+          ],
+          totalResults: 1,
+          mode: 'hybrid',
+          timeMs: 50
+        })
+      }
+    } as unknown as ServiceContainer;
+
+    mockContext = {
+      services: mockServices,
+      options: {}
+    };
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('handleSearch', () => {
+    it('should search across all stores when no stores specified', async () => {
+      const result = await handleSearch(
+        { query: 'test query', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      expect(mockServices.store.list).toHaveBeenCalled();
+      expect(mockServices.search.search).toHaveBeenCalledWith(
+        expect.objectContaining({
+          query: 'test query',
+          stores: ['store1']
+        })
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.results).toHaveLength(1);
+      expect(response.totalResults).toBe(1);
+    });
+
+    it('should use specified stores', async () => {
+      await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10, stores: ['store1'] },
+        mockContext
+      );
+
+      expect(mockServices.store.getByIdOrName).toHaveBeenCalledWith('store1');
+    });
+
+    it('should throw if store not found', async () => {
+      vi.mocked(mockServices.store.getByIdOrName).mockResolvedValue(undefined);
+
+      await expect(
+        handleSearch(
+          { query: 'test', detail: 'minimal', limit: 10, stores: ['nonexistent'] },
+          mockContext
+        )
+      ).rejects.toThrow('Store not found');
+    });
+
+    it('should initialize all stores', async () => {
+      await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      expect(mockServices.lance.initialize).toHaveBeenCalledWith('store1');
+    });
+
+    it('should throw on store initialization error', async () => {
+      vi.mocked(mockServices.lance.initialize).mockRejectedValue(
+        new Error('Lance initialization failed')
+      );
+
+      await expect(
+        handleSearch(
+          { query: 'test', detail: 'minimal', limit: 10 },
+          mockContext
+        )
+      ).rejects.toThrow('Failed to initialize vector stores');
+    });
+
+    it('should cache search results', async () => {
+      await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      // Verify cache was populated
+      const cached = resultCache.get('doc1');
+      expect(cached).toBeDefined();
+      expect(cached?.id).toBe('doc1');
+    });
+
+    it('should calculate estimated tokens', async () => {
+      const result = await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.estimatedTokens).toBeGreaterThan(0);
+    });
+
+    it('should add repoRoot for repo stores', async () => {
+      vi.mocked(mockServices.store.getByIdOrName).mockResolvedValue({
+        id: 'store1',
+        name: 'Test Repo',
+        type: 'repo',
+        path: '/repos/test',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        status: 'ready',
+        description: 'Test'
+      });
+
+      const result = await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.results[0]?.summary.repoRoot).toBe('/repos/test');
+    });
+
+    it('should not add repoRoot for file stores', async () => {
+      const result = await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.results[0]?.summary.repoRoot).toBeUndefined();
+    });
+
+    it('should include storeName in results', async () => {
+      const result = await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.results[0]?.summary.storeName).toBe('Test Store');
+    });
+
+    it('should include search metadata in response', async () => {
+      const result = await handleSearch(
+        { query: 'test', detail: 'minimal', limit: 10 },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response).toHaveProperty('totalResults', 1);
+      expect(response).toHaveProperty('estimatedTokens');
+      expect(response).toHaveProperty('mode', 'hybrid');
+      expect(response).toHaveProperty('timeMs', 50);
+    });
+  });
+
+  describe('handleGetFullContext', () => {
+    beforeEach(() => {
+      // Seed cache with a result
+      resultCache.set('doc1', {
+        id: 'doc1',
+        score: 0.95,
+        content: 'test content for get full context',
+        metadata: { storeId: 'store1', docId: 'doc1' },
+        summary: { file: 'test.ts', line: 1 }
+      });
+    });
+
+    it('should return cached result if already full', async () => {
+      // Set up cache with full result
+      resultCache.set('doc1', {
+        id: 'doc1',
+        score: 0.95,
+        content: 'test content',
+        metadata: { storeId: 'store1', docId: 'doc1' },
+        summary: { file: 'test.ts', line: 1 },
+        full: { code: 'full code here' }
+      });
+
+      const result = await handleGetFullContext(
+        { resultId: 'doc1' },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.id).toBe('doc1');
+      expect(response.full).toBeDefined();
+      expect(response.full.code).toBe('full code here');
+
+      // Should not create services or search again
+      expect(mockServices.store.getByIdOrName).not.toHaveBeenCalled();
+    });
+
+    it('should throw if result not in cache', async () => {
+      await expect(
+        handleGetFullContext(
+          { resultId: 'nonexistent' },
+          mockContext
+        )
+      ).rejects.toThrow('Result not found in cache');
+    });
+
+    it('should re-query for full context if not already full', async () => {
+      vi.mocked(mockServices.search.search).mockResolvedValue({
+        results: [
+          {
+            id: 'doc1',
+            score: 0.95,
+            content: 'test content',
+            metadata: { storeId: 'store1', docId: 'doc1' },
+            summary: { file: 'test.ts', line: 1 },
+            full: { code: 'full code from re-query' }
+          }
+        ],
+        totalResults: 1,
+        mode: 'hybrid',
+        timeMs: 50
+      });
+
+      const result = await handleGetFullContext(
+        { resultId: 'doc1' },
+        mockContext
+      );
+
+      expect(mockServices.store.getByIdOrName).toHaveBeenCalledWith('store1');
+      expect(mockServices.lance.initialize).toHaveBeenCalledWith('store1');
+      expect(mockServices.search.search).toHaveBeenCalledWith(
+        expect.objectContaining({
+          detail: 'full',
+          limit: 1
+        })
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.full?.code).toBe('full code from re-query');
+    });
+
+    it('should throw if store not found', async () => {
+      vi.mocked(mockServices.store.getByIdOrName).mockResolvedValue(undefined);
+
+      await expect(
+        handleGetFullContext(
+          { resultId: 'doc1' },
+          mockContext
+        )
+      ).rejects.toThrow('Store not found');
+    });
+
+    it('should return cached result with warning if re-query fails', async () => {
+      vi.mocked(mockServices.search.search).mockResolvedValue({
+        results: [], // No matching result found
+        totalResults: 0,
+        mode: 'hybrid',
+        timeMs: 50
+      });
+
+      const result = await handleGetFullContext(
+        { resultId: 'doc1' },
+        mockContext
+      );
+
+      const response = JSON.parse(result.content[0]?.text ?? '{}');
+      expect(response.id).toBe('doc1');
+      expect(response.warning).toContain('Could not retrieve full context');
+    });
+
+    it('should update cache with full result after re-query', async () => {
+      vi.mocked(mockServices.search.search).mockResolvedValue({
+        results: [
+          {
+            id: 'doc1',
+            score: 0.95,
+            content: 'test content',
+            metadata: { storeId: 'store1', docId: 'doc1' },
+            summary: { file: 'test.ts', line: 1 },
+            full: { code: 'full code from re-query' }
+          }
+        ],
+        totalResults: 1,
+        mode: 'hybrid',
+        timeMs: 50
+      });
+
+      await handleGetFullContext(
+        { resultId: 'doc1' },
+        mockContext
+      );
+
+      const cached = resultCache.get('doc1');
+      expect(cached?.full).toBeDefined();
+      expect(cached?.full?.code).toBe('full code from re-query');
+    });
+  });
+});

package/src/mcp/handlers/search.handler.ts

@@ -0,0 +1,209 @@
+import type { ToolHandler, ToolResponse } from '../types.js';
+import type { SearchArgs, GetFullContextArgs } from '../schemas/index.js';
+import { SearchArgsSchema, GetFullContextArgsSchema } from '../schemas/index.js';
+import type { SearchQuery, DocumentId, StoreId } from '../../types/index.js';
+import { LRUCache } from '../cache.js';
+import type { SearchResult } from '../../types/search.js';
+
+// Create result cache for get_full_context
+// Uses LRU cache to prevent memory leaks (max 1000 items)
+export const resultCache = new LRUCache<DocumentId, SearchResult>(1000);
+
+/**
+ * Handle search requests
+ *
+ * Searches across specified stores (or all stores if none specified) using
+ * hybrid vector + FTS search. Results are cached for get_full_context retrieval.
+ */
+export const handleSearch: ToolHandler<SearchArgs> = async (
+  args,
+  context
+): Promise<ToolResponse> => {
+  // Validate arguments with Zod
+  const validated = SearchArgsSchema.parse(args);
+
+  const { services } = context;
+
+  // Get all stores if none specified, resolve store names to IDs
+  const storeIds: StoreId[] = validated.stores !== undefined
+    ? await Promise.all(validated.stores.map(async (s) => {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const store = await services.store.getByIdOrName(s as StoreId);
+        if (!store) {
+          throw new Error(`Store not found: ${s}`);
+        }
+        return store.id;
+      }))
+    : (await services.store.list()).map(s => s.id);
+
+  // Initialize stores with error handling
+  try {
+    for (const storeId of storeIds) {
+      await services.lance.initialize(storeId);
+    }
+  } catch (error) {
+    throw new Error(
+      `Failed to initialize vector stores: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  // Perform search
+  const searchQuery: SearchQuery = {
+    query: validated.query,
+    stores: storeIds,
+    mode: 'hybrid',
+    limit: validated.limit,
+    detail: validated.detail
+  };
+
+  const results = await services.search.search(searchQuery);
+
+  // Cache results for get_full_context (with LRU eviction)
+  for (const result of results.results) {
+    resultCache.set(result.id, result);
+  }
+
+  // Calculate estimated tokens
+  const estimatedTokens = results.results.reduce((sum, r) => {
+    let tokens = 100; // Base for summary
+    if (r.context) tokens += 200;
+    if (r.full) tokens += 800;
+    return sum + tokens;
+  }, 0);
+
+  // Add repoRoot to results for cloned repos
+  const enhancedResults = await Promise.all(results.results.map(async (r) => {
+    const storeId = r.metadata.storeId;
+    const store = await services.store.getByIdOrName(storeId);
+
+    return {
+      id: r.id,
+      score: r.score,
+      summary: {
+        ...r.summary,
+        storeName: store?.name,
+        repoRoot: store !== undefined && store.type === 'repo' ? store.path : undefined
+      },
+      context: r.context,
+      full: r.full
+    };
+  }));
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({
+          results: enhancedResults,
+          totalResults: results.totalResults,
+          estimatedTokens,
+          mode: results.mode,
+          timeMs: results.timeMs
+        }, null, 2)
+      }
+    ]
+  };
+};
+
+/**
+ * Handle get_full_context requests
+ *
+ * Retrieves full context for a previously cached search result.
+ * If the result isn't already full, re-queries with full detail level.
+ */
+export const handleGetFullContext: ToolHandler<GetFullContextArgs> = async (
+  args,
+  context
+): Promise<ToolResponse> => {
+  // Validate arguments with Zod
+  const validated = GetFullContextArgsSchema.parse(args);
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const resultId = validated.resultId as DocumentId;
+
+  // Check cache for result
+  const cachedResult = resultCache.get(resultId);
+
+  if (!cachedResult) {
+    throw new Error(
+      `Result not found in cache: ${resultId}. Run a search first to cache results.`
+    );
+  }
+
+  // If result already has full context, return it
+  if (cachedResult.full) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            id: cachedResult.id,
+            score: cachedResult.score,
+            summary: cachedResult.summary,
+            context: cachedResult.context,
+            full: cachedResult.full
+          }, null, 2)
+        }
+      ]
+    };
+  }
+
+  // Otherwise, re-query with full detail
+  const { services } = context;
+  const store = await services.store.getByIdOrName(cachedResult.metadata.storeId);
+
+  if (!store) {
+    throw new Error(`Store not found: ${cachedResult.metadata.storeId}`);
+  }
+
+  await services.lance.initialize(store.id);
+
+  const searchQuery: SearchQuery = {
+    query: cachedResult.content.substring(0, 100), // Use snippet of content as query
+    stores: [store.id],
+    mode: 'hybrid',
+    limit: 1,
+    detail: 'full'
+  };
+
+  const results = await services.search.search(searchQuery);
+
+  // Find matching result by ID
+  const fullResult = results.results.find(r => r.id === resultId);
+
+  if (!fullResult) {
+    // Return cached result even if we couldn't get full detail
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            id: cachedResult.id,
+            score: cachedResult.score,
+            summary: cachedResult.summary,
+            context: cachedResult.context,
+            warning: 'Could not retrieve full context, returning cached minimal result'
+          }, null, 2)
+        }
+      ]
+    };
+  }
+
+  // Update cache with full result
+  resultCache.set(resultId, fullResult);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({
+          id: fullResult.id,
+          score: fullResult.score,
+          summary: fullResult.summary,
+          context: fullResult.context,
+          full: fullResult.full
+        }, null, 2)
+      }
+    ]
+  };
+};