bluera-knowledge 0.9.21

package/src/mcp/commands/registry.ts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+import type { HandlerContext, ToolResponse } from '../types.js';
+
+/**
+ * Command definition for the execute meta-tool
+ *
+ * Each command has a name, description, optional args schema, and handler.
+ * Commands are registered in the registry and invoked via execute(command, args).
+ */
+export interface CommandDefinition {
+  /** Command name (e.g., 'stores', 'store:info', 'job:status') */
+  name: string;
+  /** Human-readable description shown in help output */
+  description: string;
+  /** Optional Zod schema for argument validation */
+  argsSchema?: z.ZodType;
+  /** Handler function that executes the command */
+  handler: CommandHandler;
+}
+
+/**
+ * Command handler function signature
+ *
+ * @param args - Validated command arguments (or empty object if no args)
+ * @param context - Handler context with services and options
+ * @returns Promise resolving to tool response
+ */
+export type CommandHandler = (
+  args: Record<string, unknown>,
+  context: HandlerContext
+) => Promise<ToolResponse>;
+
+/**
+ * Command registry - singleton that holds all registered commands
+ */
+class CommandRegistry {
+  private readonly commands = new Map<string, CommandDefinition>();
+
+  /**
+   * Register a command
+   */
+  register(command: CommandDefinition): void {
+    if (this.commands.has(command.name)) {
+      throw new Error(`Command already registered: ${command.name}`);
+    }
+    this.commands.set(command.name, command);
+  }
+
+  /**
+   * Register multiple commands at once
+   */
+  registerAll(commands: CommandDefinition[]): void {
+    for (const command of commands) {
+      this.register(command);
+    }
+  }
+
+  /**
+   * Get a command by name
+   */
+  get(name: string): CommandDefinition | undefined {
+    return this.commands.get(name);
+  }
+
+  /**
+   * Check if a command exists
+   */
+  has(name: string): boolean {
+    return this.commands.has(name);
+  }
+
+  /**
+   * Get all registered commands
+   */
+  all(): CommandDefinition[] {
+    return Array.from(this.commands.values());
+  }
+
+  /**
+   * Get commands grouped by category (prefix before colon)
+   */
+  grouped(): Map<string, CommandDefinition[]> {
+    const groups = new Map<string, CommandDefinition[]>();
+
+    for (const cmd of this.commands.values()) {
+      const colonIndex = cmd.name.indexOf(':');
+      const category = colonIndex === -1 ? 'general' : cmd.name.slice(0, colonIndex);
+
+      const existing = groups.get(category) ?? [];
+      existing.push(cmd);
+      groups.set(category, existing);
+    }
+
+    return groups;
+  }
+}
+
+/** Global command registry instance */
+export const commandRegistry = new CommandRegistry();
+
+/**
+ * Execute a command by name
+ *
+ * @param commandName - The command to execute
+ * @param args - Arguments to pass to the command
+ * @param context - Handler context
+ * @returns Promise resolving to tool response
+ */
+export async function executeCommand(
+  commandName: string,
+  args: Record<string, unknown>,
+  context: HandlerContext
+): Promise<ToolResponse> {
+  const command = commandRegistry.get(commandName);
+
+  if (command === undefined) {
+    throw new Error(
+      `Unknown command: ${commandName}. Use execute("commands") to list available commands.`
+    );
+  }
+
+  // Validate args if schema provided (Zod parse returns unknown, safe to cast after validation)
+  /* eslint-disable @typescript-eslint/consistent-type-assertions */
+  const validatedArgs: Record<string, unknown> = command.argsSchema !== undefined
+    ? (command.argsSchema.parse(args) as Record<string, unknown>)
+    : args;
+  /* eslint-enable @typescript-eslint/consistent-type-assertions */
+
+  return command.handler(validatedArgs, context);
+}
+
+/**
+ * Generate help text for a command or all commands
+ */
+export function generateHelp(commandName?: string): string {
+  if (commandName !== undefined) {
+    const command = commandRegistry.get(commandName);
+    if (command === undefined) {
+      throw new Error(`Unknown command: ${commandName}`);
+    }
+
+    const lines = [
+      `Command: ${command.name}`,
+      `Description: ${command.description}`,
+      ''
+    ];
+
+    if (command.argsSchema !== undefined) {
+      lines.push('Arguments:');
+      // Extract schema shape for documentation
+      const schema = command.argsSchema;
+      if (schema instanceof z.ZodObject) {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const shape = schema.shape as Record<string, z.ZodType>;
+        for (const [key, fieldSchema] of Object.entries(shape)) {
+          const isOptional = fieldSchema.safeParse(undefined).success;
+          const desc = fieldSchema.description ?? '';
+          lines.push(`  ${key}${isOptional ? ' (optional)' : ''}: ${desc}`);
+        }
+      }
+    } else {
+      lines.push('Arguments: none');
+    }
+
+    return lines.join('\n');
+  }
+
+  // Generate help for all commands
+  const groups = commandRegistry.grouped();
+  const lines = ['Available commands:', ''];
+
+  for (const [category, commands] of groups) {
+    lines.push(`${category}:`);
+    for (const cmd of commands) {
+      lines.push(`  ${cmd.name} - ${cmd.description}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Use execute("help", {command: "name"}) for detailed command help.');
+
+  return lines.join('\n');
+}

package/src/mcp/commands/store.commands.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import type { CommandDefinition } from './registry.js';
+import type {
+  ListStoresArgs,
+  GetStoreInfoArgs,
+  CreateStoreArgs,
+  IndexStoreArgs,
+  DeleteStoreArgs
+} from '../schemas/index.js';
+import {
+  handleListStores,
+  handleGetStoreInfo,
+  handleCreateStore,
+  handleIndexStore,
+  handleDeleteStore
+} from '../handlers/store.handler.js';
+
+/**
+ * Store management commands for the execute meta-tool
+ *
+ * These commands wrap the existing store handlers, providing
+ * a unified interface through the execute command.
+ *
+ * Note: Type assertions are necessary here because CommandHandler uses
+ * Record<string, unknown> for generic command args, while handlers expect
+ * specific typed args. Zod validates at runtime before the cast.
+ */
+/* eslint-disable @typescript-eslint/consistent-type-assertions */
+export const storeCommands: CommandDefinition[] = [
+  {
+    name: 'stores',
+    description: 'List all indexed knowledge stores',
+    argsSchema: z.object({
+      type: z.enum(['file', 'repo', 'web']).optional().describe('Filter by store type')
+    }),
+    handler: (args, context) => handleListStores(args as unknown as ListStoresArgs, context)
+  },
+  {
+    name: 'store:info',
+    description: 'Get detailed information about a specific store',
+    argsSchema: z.object({
+      store: z.string().min(1).describe('Store name or ID')
+    }),
+    handler: (args, context) => handleGetStoreInfo(args as unknown as GetStoreInfoArgs, context)
+  },
+  {
+    name: 'store:create',
+    description: 'Create a new knowledge store from git URL or local path',
+    argsSchema: z.object({
+      name: z.string().min(1).describe('Store name'),
+      type: z.enum(['file', 'repo']).describe('Store type'),
+      source: z.string().min(1).describe('Git URL or local path'),
+      branch: z.string().optional().describe('Git branch (for repo type)'),
+      description: z.string().optional().describe('Store description')
+    }),
+    handler: (args, context) => handleCreateStore(args as unknown as CreateStoreArgs, context)
+  },
+  {
+    name: 'store:index',
+    description: 'Re-index a knowledge store to update search data',
+    argsSchema: z.object({
+      store: z.string().min(1).describe('Store name or ID')
+    }),
+    handler: (args, context) => handleIndexStore(args as unknown as IndexStoreArgs, context)
+  },
+  {
+    name: 'store:delete',
+    description: 'Delete a knowledge store and all associated data',
+    argsSchema: z.object({
+      store: z.string().min(1).describe('Store name or ID')
+    }),
+    handler: (args, context) => handleDeleteStore(args as unknown as DeleteStoreArgs, context)
+  }
+];
+/* eslint-enable @typescript-eslint/consistent-type-assertions */

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

@@ -0,0 +1,179 @@
+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

@@ -0,0 +1,24 @@
+import type { ToolHandler, ToolResponse } from '../types.js';
+import type { ExecuteArgs } from '../schemas/index.js';
+import { ExecuteArgsSchema } from '../schemas/index.js';
+// Import commands module to register all commands
+import '../commands/index.js';
+import { executeCommand } from '../commands/index.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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { ToolHandler } from '../types.js';
+import {
+  SearchArgsSchema,
+  GetFullContextArgsSchema
+} from '../schemas/index.js';
+import {
+  handleSearch,
+  handleGetFullContext
+} from './search.handler.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
+  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

@@ -0,0 +1,189 @@
+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');
+      }
+    });
+  });
+});