bluera-knowledge 0.13.3 → 0.14.1

package/src/mcp/commands/sync.commands.ts

@@ -1,263 +0,0 @@
-import { z } from 'zod';
-import { JobService } from '../../services/job.service.js';
-import { StoreDefinitionService } from '../../services/store-definition.service.js';
-import {
-  isFileStoreDefinition,
-  isRepoStoreDefinition,
-  isWebStoreDefinition,
-} from '../../types/store-definition.js';
-import { spawnBackgroundWorker } from '../../workers/spawn-worker.js';
-import type { CommandDefinition } from './registry.js';
-import type { StoreDefinition } from '../../types/store-definition.js';
-import type { HandlerContext, ToolResponse } from '../types.js';
-
-/**
- * Arguments for stores:sync command
- */
-export interface SyncStoresArgs {
-  prune?: boolean;
-  dryRun?: boolean;
-  reindex?: boolean;
-}
-
-/**
- * Result of a sync operation
- */
-interface SyncResult {
-  created: string[];
-  skipped: string[];
-  failed: Array<{ name: string; error: string }>;
-  orphans: string[];
-  pruned?: string[];
-  dryRun?: boolean;
-  wouldCreate?: string[];
-  wouldPrune?: string[];
-  reindexJobs?: Array<{ store: string; jobId: string }>;
-  wouldReindex?: string[];
-}
-
-/**
- * Handle stores:sync command
- *
- * Syncs stores from definitions config:
- * - Creates missing stores from definitions
- * - Reports stores not in definitions (orphans)
- * - Optionally prunes orphan stores
- */
-export async function handleStoresSync(
-  args: SyncStoresArgs,
-  context: HandlerContext
-): Promise<ToolResponse> {
-  const { services, options } = context;
-  const projectRoot = options.projectRoot;
-
-  if (projectRoot === undefined) {
-    throw new Error('Project root is required for stores:sync');
-  }
-
-  const defService = new StoreDefinitionService(projectRoot);
-  const config = await defService.load();
-
-  const result: SyncResult = {
-    created: [],
-    skipped: [],
-    failed: [],
-    orphans: [],
-  };
-
-  if (args.dryRun === true) {
-    result.dryRun = true;
-    result.wouldCreate = [];
-    result.wouldPrune = [];
-  }
-
-  // Get existing stores
-  const existingStores = await services.store.list();
-  const existingNames = new Set(existingStores.map((s) => s.name));
-
-  // Process each definition
-  for (const def of config.stores) {
-    if (existingNames.has(def.name)) {
-      result.skipped.push(def.name);
-      continue;
-    }
-
-    if (args.dryRun === true) {
-      result.wouldCreate?.push(def.name);
-      continue;
-    }
-
-    // Try to create the store
-    const createResult = await createStoreFromDefinition(def, defService, services, context);
-    if (createResult.success) {
-      result.created.push(def.name);
-    } else {
-      result.failed.push({ name: def.name, error: createResult.error });
-    }
-  }
-
-  // Find orphans (stores not in definitions)
-  const definedNames = new Set(config.stores.map((d) => d.name));
-  for (const store of existingStores) {
-    if (!definedNames.has(store.name)) {
-      result.orphans.push(store.name);
-    }
-  }
-
-  // Prune orphans if requested
-  if (args.prune === true && result.orphans.length > 0) {
-    if (args.dryRun === true) {
-      result.wouldPrune = [...result.orphans];
-    } else {
-      result.pruned = [];
-      for (const orphanName of result.orphans) {
-        const store = await services.store.getByName(orphanName);
-        if (store !== undefined) {
-          const deleteResult = await services.store.delete(store.id, { skipDefinitionSync: true });
-          if (deleteResult.success) {
-            result.pruned.push(orphanName);
-          }
-        }
-      }
-    }
-  }
-
-  // Re-index existing stores if requested
-  if (args.reindex === true && result.skipped.length > 0) {
-    if (args.dryRun === true) {
-      result.wouldReindex = [...result.skipped];
-    } else {
-      result.reindexJobs = [];
-      const dataDir = options.dataDir;
-      if (dataDir === undefined) {
-        throw new Error('dataDir is required for reindexing');
-      }
-      const jobService = new JobService(dataDir);
-
-      for (const storeName of result.skipped) {
-        const store = await services.store.getByName(storeName);
-        if (store !== undefined) {
-          const job = jobService.createJob({
-            type: 'index',
-            details: { storeId: store.id, storeName: store.name },
-            message: `Re-indexing ${storeName}...`,
-          });
-          spawnBackgroundWorker(job.id, dataDir);
-          result.reindexJobs.push({ store: storeName, jobId: job.id });
-        }
-      }
-    }
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(result, null, 2),
-      },
-    ],
-  };
-}
-
-/**
- * Create a store from a definition
- */
-async function createStoreFromDefinition(
-  def: StoreDefinition,
-  defService: StoreDefinitionService,
-  services: HandlerContext['services'],
-  _context: HandlerContext
-): Promise<{ success: true } | { success: false; error: string }> {
-  try {
-    if (isFileStoreDefinition(def)) {
-      // Resolve path relative to project root
-      const resolvedPath = defService.resolvePath(def.path);
-      const createResult = await services.store.create(
-        {
-          name: def.name,
-          type: 'file',
-          path: resolvedPath,
-          description: def.description,
-          tags: def.tags,
-        },
-        { skipDefinitionSync: true } // Don't re-add to definitions
-      );
-      if (!createResult.success) {
-        return { success: false, error: createResult.error.message };
-      }
-      return { success: true };
-    }
-
-    if (isRepoStoreDefinition(def)) {
-      const createResult = await services.store.create(
-        {
-          name: def.name,
-          type: 'repo',
-          url: def.url,
-          branch: def.branch,
-          depth: def.depth,
-          description: def.description,
-          tags: def.tags,
-        },
-        { skipDefinitionSync: true }
-      );
-      if (!createResult.success) {
-        return { success: false, error: createResult.error.message };
-      }
-      return { success: true };
-    }
-
-    if (isWebStoreDefinition(def)) {
-      const createResult = await services.store.create(
-        {
-          name: def.name,
-          type: 'web',
-          url: def.url,
-          depth: def.depth,
-          description: def.description,
-          tags: def.tags,
-        },
-        { skipDefinitionSync: true }
-      );
-      if (!createResult.success) {
-        return { success: false, error: createResult.error.message };
-      }
-      return { success: true };
-    }
-
-    return { success: false, error: 'Unknown store definition type' };
-  } catch (error) {
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-/**
- * Sync commands for the execute meta-tool
- */
-export const syncCommands: CommandDefinition[] = [
-  {
-    name: 'stores:sync',
-    description: 'Sync stores from definitions config (bootstrap on fresh clone)',
-    argsSchema: z.object({
-      prune: z.boolean().optional().describe('Remove stores not in definitions'),
-      dryRun: z.boolean().optional().describe('Show what would happen without making changes'),
-      reindex: z.boolean().optional().describe('Re-index existing stores after sync'),
-    }),
-    handler: (args: Record<string, unknown>, context: HandlerContext): Promise<ToolResponse> => {
-      const syncArgs: SyncStoresArgs = {};
-      if (typeof args['prune'] === 'boolean') {
-        syncArgs.prune = args['prune'];
-      }
-      if (typeof args['dryRun'] === 'boolean') {
-        syncArgs.dryRun = args['dryRun'];
-      }
-      if (typeof args['reindex'] === 'boolean') {
-        syncArgs.reindex = args['reindex'];
-      }
-      return handleStoresSync(syncArgs, context);
-    },
-  },
-];

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

@@ -1,179 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { handleExecute } from './execute.handler.js';
-import type { HandlerContext } from '../types.js';
-import type { ExecuteArgs } from '../schemas/index.js';
-import { JobService } from '../../services/job.service.js';
-import { mkdtempSync, rmSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-describe('execute.handler', () => {
-  let tempDir: string;
-  let mockContext: HandlerContext;
-
-  beforeEach(() => {
-    tempDir = mkdtempSync(join(tmpdir(), 'execute-handler-test-'));
-    mockContext = {
-      services: {
-        store: {
-          list: async () => [],
-          getByIdOrName: async () => undefined,
-          create: async () => ({ success: false, error: { message: 'Not implemented in test' } }),
-          delete: async () => ({ success: false, error: { message: 'Not implemented in test' } }),
-        },
-        lance: {
-          deleteStore: async () => {},
-        },
-      } as unknown as HandlerContext['services'],
-      options: { dataDir: tempDir },
-    };
-  });
-
-  afterEach(() => {
-    rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  describe('meta commands', () => {
-    it('should handle "commands" command', async () => {
-      const args: ExecuteArgs = { command: 'commands' };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.commands).toBeDefined();
-      expect(Array.isArray(data.commands)).toBe(true);
-
-      // Should include known commands
-      const commandNames = data.commands.map((c: { name: string }) => c.name);
-      expect(commandNames).toContain('stores');
-      expect(commandNames).toContain('store:create');
-      expect(commandNames).toContain('jobs');
-      expect(commandNames).toContain('help');
-    });
-
-    it('should handle "help" command without args', async () => {
-      const args: ExecuteArgs = { command: 'help' };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const text = result.content[0].text;
-      expect(text).toContain('Available commands');
-      expect(text).toContain('stores');
-      expect(text).toContain('store:');
-      expect(text).toContain('job:');
-    });
-
-    it('should handle "help" command with specific command', async () => {
-      const args: ExecuteArgs = { command: 'help', args: { command: 'stores' } };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const text = result.content[0].text;
-      expect(text).toContain('Command: stores');
-      expect(text).toContain('Description:');
-    });
-  });
-
-  describe('store commands', () => {
-    it('should handle "stores" command', async () => {
-      const args: ExecuteArgs = { command: 'stores' };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.stores).toBeDefined();
-      expect(Array.isArray(data.stores)).toBe(true);
-    });
-
-    it('should handle "store:info" command', async () => {
-      const args: ExecuteArgs = {
-        command: 'store:info',
-        args: { store: 'nonexistent' },
-      };
-
-      // Should throw since store doesn't exist
-      await expect(handleExecute(args, mockContext)).rejects.toThrow('Store not found');
-    });
-  });
-
-  describe('job commands', () => {
-    it('should handle "jobs" command', async () => {
-      const args: ExecuteArgs = { command: 'jobs' };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.jobs).toBeDefined();
-      expect(Array.isArray(data.jobs)).toBe(true);
-    });
-
-    it('should handle "job:status" command', async () => {
-      // Create a job first
-      const jobService = new JobService(tempDir);
-      const job = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'test-store' },
-        message: 'Testing...',
-      });
-
-      const args: ExecuteArgs = {
-        command: 'job:status',
-        args: { jobId: job.id },
-      };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.id).toBe(job.id);
-      expect(data.status).toBe('pending');
-    });
-
-    it('should handle "job:cancel" command', async () => {
-      // Create a job first
-      const jobService = new JobService(tempDir);
-      const job = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'test-store' },
-        message: 'Testing...',
-      });
-
-      const args: ExecuteArgs = {
-        command: 'job:cancel',
-        args: { jobId: job.id },
-      };
-      const result = await handleExecute(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.success).toBe(true);
-      expect(data.job.status).toBe('cancelled');
-    });
-  });
-
-  describe('error handling', () => {
-    it('should throw for unknown command', async () => {
-      const args: ExecuteArgs = { command: 'unknown-command' };
-
-      await expect(handleExecute(args, mockContext)).rejects.toThrow(
-        'Unknown command: unknown-command'
-      );
-    });
-
-    it('should validate command is required', async () => {
-      const args = {} as ExecuteArgs;
-
-      await expect(handleExecute(args, mockContext)).rejects.toThrow();
-    });
-
-    it('should throw for help on unknown command', async () => {
-      const args: ExecuteArgs = {
-        command: 'help',
-        args: { command: 'nonexistent' },
-      };
-
-      await expect(handleExecute(args, mockContext)).rejects.toThrow(
-        'Unknown command: nonexistent'
-      );
-    });
-  });
-});

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

@@ -1,23 +0,0 @@
-// Import commands module - side effect registers all commands, then use executeCommand
-import { executeCommand } from '../commands/index.js';
-import { ExecuteArgsSchema } from '../schemas/index.js';
-import type { ExecuteArgs } from '../schemas/index.js';
-import type { ToolHandler, ToolResponse } from '../types.js';
-
-/**
- * Handle execute requests
- *
- * This is the meta-tool handler that routes to registered commands.
- * It consolidates store and job management into a single tool surface.
- */
-export const handleExecute: ToolHandler<ExecuteArgs> = async (
-  args,
-  context
-): Promise<ToolResponse> => {
-  // Validate arguments with Zod
-  const validated = ExecuteArgsSchema.parse(args);
-
-  const commandArgs = validated.args ?? {};
-
-  return executeCommand(validated.command, commandArgs, context);
-};

package/src/mcp/handlers/index.ts

@@ -1,39 +0,0 @@
-import { z } from 'zod';
-import { handleSearch, handleGetFullContext } from './search.handler.js';
-import { SearchArgsSchema, GetFullContextArgsSchema } from '../schemas/index.js';
-import type { ToolHandler } from '../types.js';
-
-/**
- * Tool definition with schema and handler
- */
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  schema: z.ZodType;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- heterogeneous tool registry requires any; schema provides runtime type safety via Zod validation
-  handler: ToolHandler<any>;
-}
-
-/**
- * Registry of native MCP tools
- *
- * Only search and get_full_context are native tools with full schemas.
- * Store and job management is consolidated into the execute meta-tool
- * (see commands/ directory and execute.handler.ts).
- */
-export const tools: ToolDefinition[] = [
-  {
-    name: 'search',
-    description:
-      'Search all indexed knowledge stores with pattern detection and AI-optimized results. Returns structured code units with progressive context layers.',
-    schema: SearchArgsSchema,
-    handler: handleSearch,
-  },
-  {
-    name: 'get_full_context',
-    description:
-      'Get complete code and context for a specific search result by ID. Use this after search to get full implementation details.',
-    schema: GetFullContextArgsSchema,
-    handler: handleGetFullContext,
-  },
-];

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

@@ -1,189 +0,0 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-import { handleCheckJobStatus, handleListJobs, handleCancelJob } from './job.handler.js';
-import type { HandlerContext } from '../types.js';
-import type { CheckJobStatusArgs, ListJobsArgs, CancelJobArgs } from '../schemas/index.js';
-import { JobService } from '../../services/job.service.js';
-import { mkdtempSync, rmSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-describe('job.handler', () => {
-  let tempDir: string;
-  let mockContext: HandlerContext;
-
-  beforeEach(() => {
-    tempDir = mkdtempSync(join(tmpdir(), 'job-handler-test-'));
-    mockContext = {
-      services: {} as any,
-      options: { dataDir: tempDir },
-    };
-  });
-
-  afterEach(() => {
-    rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  describe('handleCheckJobStatus', () => {
-    it('should return job status', async () => {
-      const jobService = new JobService(tempDir);
-      const job = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'test-store' },
-        message: 'Indexing...',
-      });
-
-      const args: CheckJobStatusArgs = { jobId: job.id };
-      const result = await handleCheckJobStatus(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.id).toBe(job.id);
-      expect(data.status).toBe('pending');
-    });
-
-    it('should throw if job not found', async () => {
-      const args: CheckJobStatusArgs = { jobId: 'nonexistent' };
-
-      try {
-        await handleCheckJobStatus(args, mockContext);
-        expect.fail('Should have thrown');
-      } catch (error) {
-        expect(error).toBeInstanceOf(Error);
-        expect((error as Error).message).toBe('Job not found: nonexistent');
-      }
-    });
-
-    it('should validate arguments with Zod', async () => {
-      const invalidArgs = { jobId: 123 } as any;
-
-      try {
-        await handleCheckJobStatus(invalidArgs, mockContext);
-        expect.fail('Should have thrown');
-      } catch (error) {
-        expect(error).toBeDefined();
-      }
-    });
-  });
-
-  describe('handleListJobs', () => {
-    it('should list all jobs', async () => {
-      const jobService = new JobService(tempDir);
-      jobService.createJob({
-        type: 'index',
-        details: { storeId: 'store1' },
-        message: 'Indexing store1',
-      });
-      jobService.createJob({
-        type: 'clone',
-        details: { url: 'https://example.com' },
-        message: 'Cloning repo',
-      });
-
-      const args: ListJobsArgs = {};
-      const result = await handleListJobs(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.jobs).toHaveLength(2);
-    });
-
-    it('should filter by status', async () => {
-      const jobService = new JobService(tempDir);
-      const job1 = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'store1' },
-        message: 'Indexing',
-      });
-      jobService.createJob({
-        type: 'clone',
-        details: { url: 'https://example.com' },
-        message: 'Cloning',
-      });
-
-      // Update job1 status
-      jobService.updateJob(job1.id, { status: 'completed' });
-
-      const args: ListJobsArgs = { status: 'completed' };
-      const result = await handleListJobs(args, mockContext);
-
-      const data = JSON.parse(result.content[0].text);
-      expect(data.jobs).toHaveLength(1);
-      expect(data.jobs[0].status).toBe('completed');
-    });
-
-    it('should filter active jobs only', async () => {
-      const jobService = new JobService(tempDir);
-      const job1 = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'store1' },
-        message: 'Indexing',
-      });
-      jobService.createJob({
-        type: 'clone',
-        details: { url: 'https://example.com' },
-        message: 'Cloning',
-      });
-
-      jobService.updateJob(job1.id, { status: 'completed' });
-
-      const args: ListJobsArgs = { activeOnly: true };
-      const result = await handleListJobs(args, mockContext);
-
-      const data = JSON.parse(result.content[0].text);
-      expect(data.jobs).toHaveLength(1);
-      expect(data.jobs[0].status).not.toBe('completed');
-    });
-  });
-
-  describe('handleCancelJob', () => {
-    it('should cancel a pending job', async () => {
-      const jobService = new JobService(tempDir);
-      const job = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'test-store' },
-        message: 'Indexing...',
-      });
-
-      const args: CancelJobArgs = { jobId: job.id };
-      const result = await handleCancelJob(args, mockContext);
-
-      expect(result.content).toHaveLength(1);
-      const data = JSON.parse(result.content[0].text);
-      expect(data.success).toBe(true);
-      expect(data.job.status).toBe('cancelled');
-    });
-
-    it('should throw if job not found', async () => {
-      const args: CancelJobArgs = { jobId: 'nonexistent' };
-
-      try {
-        await handleCancelJob(args, mockContext);
-        expect.fail('Should have thrown');
-      } catch (error) {
-        expect(error).toBeInstanceOf(Error);
-        expect((error as Error).message).toBe('Job nonexistent not found');
-      }
-    });
-
-    it('should throw if job already completed', async () => {
-      const jobService = new JobService(tempDir);
-      const job = jobService.createJob({
-        type: 'index',
-        details: { storeId: 'test-store' },
-        message: 'Indexing...',
-      });
-
-      jobService.updateJob(job.id, { status: 'completed' });
-
-      const args: CancelJobArgs = { jobId: job.id };
-
-      try {
-        await handleCancelJob(args, mockContext);
-        expect.fail('Should have thrown');
-      } catch (error) {
-        expect(error).toBeInstanceOf(Error);
-        expect((error as Error).message).toBe('Cannot cancel completed job');
-      }
-    });
-  });
-});