bluera-knowledge 0.14.0 → 0.14.2

package/src/mcp/commands/registry.ts

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

@@ -1,75 +0,0 @@
-import { z } from 'zod';
-import {
-  handleListStores,
-  handleGetStoreInfo,
-  handleCreateStore,
-  handleIndexStore,
-  handleDeleteStore,
-} from '../handlers/store.handler.js';
-import type { CommandDefinition } from './registry.js';
-import type {
-  ListStoresArgs,
-  GetStoreInfoArgs,
-  CreateStoreArgs,
-  IndexStoreArgs,
-  DeleteStoreArgs,
-} from '../schemas/index.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/commands/sync.commands.test.ts

@@ -1,371 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { rm, mkdtemp, mkdir } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { syncCommands, handleStoresSync } from './sync.commands.js';
-import { StoreService } from '../../services/store.service.js';
-import { StoreDefinitionService } from '../../services/store-definition.service.js';
-import type { HandlerContext } from '../types.js';
-import type { ServiceContainer } from '../../services/index.js';
-
-// Mock spawnBackgroundWorker
-vi.mock('../../workers/spawn-worker.js', () => ({
-  spawnBackgroundWorker: vi.fn(),
-}));
-
-/**
- * Create a minimal mock service container for testing
- */
-function createMockServices(storeService: StoreService): ServiceContainer {
-  return {
-    store: storeService,
-    // Other services not needed for sync tests
-    config: {} as ServiceContainer['config'],
-    search: {} as ServiceContainer['search'],
-    index: {} as ServiceContainer['index'],
-    lance: {} as ServiceContainer['lance'],
-    embeddings: {} as ServiceContainer['embeddings'],
-    codeGraph: {} as ServiceContainer['codeGraph'],
-    pythonBridge: {} as ServiceContainer['pythonBridge'],
-  };
-}
-
-describe('sync.commands', () => {
-  describe('command definition', () => {
-    it('exports stores:sync command', () => {
-      const syncCmd = syncCommands.find((c) => c.name === 'stores:sync');
-      expect(syncCmd).toBeDefined();
-      expect(syncCmd?.description).toContain('Sync');
-    });
-
-    it('has correct args schema', () => {
-      const syncCmd = syncCommands.find((c) => c.name === 'stores:sync');
-      expect(syncCmd?.argsSchema).toBeDefined();
-
-      // Valid empty args
-      const result1 = syncCmd?.argsSchema?.safeParse({});
-      expect(result1?.success).toBe(true);
-
-      // Valid with options
-      const result2 = syncCmd?.argsSchema?.safeParse({
-        prune: true,
-        dryRun: true,
-      });
-      expect(result2?.success).toBe(true);
-
-      // Valid with reindex option
-      const result3 = syncCmd?.argsSchema?.safeParse({
-        reindex: true,
-        prune: true,
-        dryRun: true,
-      });
-      expect(result3?.success).toBe(true);
-    });
-  });
-
-  describe('handleStoresSync', () => {
-    let projectRoot: string;
-    let dataDir: string;
-    let storeService: StoreService;
-    let defService: StoreDefinitionService;
-    let context: HandlerContext;
-
-    beforeEach(async () => {
-      projectRoot = await mkdtemp(join(tmpdir(), 'sync-test-'));
-      dataDir = join(projectRoot, '.bluera/bluera-knowledge/data');
-      defService = new StoreDefinitionService(projectRoot);
-      storeService = new StoreService(dataDir, { definitionService: defService });
-      await storeService.initialize();
-
-      context = {
-        services: createMockServices(storeService),
-        options: { projectRoot, dataDir },
-      };
-    });
-
-    afterEach(async () => {
-      await rm(projectRoot, { recursive: true, force: true });
-    });
-
-    describe('creates missing stores', () => {
-      it('creates file store from definition', async () => {
-        // Create a directory to reference
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        // Add definition manually (simulating config from git)
-        await defService.addDefinition({
-          type: 'file',
-          name: 'my-docs',
-          path: './docs',
-          description: 'Documentation',
-        });
-
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.created).toContain('my-docs');
-        expect(response.skipped).toHaveLength(0);
-        expect(response.failed).toHaveLength(0);
-
-        // Verify store was created
-        const store = await storeService.getByName('my-docs');
-        expect(store).toBeDefined();
-        expect(store?.type).toBe('file');
-      });
-
-      it('creates web store from definition', async () => {
-        // Add web store definition
-        await defService.addDefinition({
-          type: 'web',
-          name: 'api-docs',
-          url: 'https://example.com/docs',
-          depth: 2,
-        });
-
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.created).toContain('api-docs');
-
-        const store = await storeService.getByName('api-docs');
-        expect(store).toBeDefined();
-        expect(store?.type).toBe('web');
-      });
-    });
-
-    describe('skips existing stores', () => {
-      it('skips store that already exists', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        // Create store first (this auto-adds the definition via the integration)
-        await storeService.create({
-          name: 'existing-docs',
-          type: 'file',
-          path: docsDir,
-        });
-
-        // Definition was auto-added, so sync should skip this store
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.skipped).toContain('existing-docs');
-        expect(response.created).toHaveLength(0);
-      });
-    });
-
-    describe('reports orphans', () => {
-      it('reports stores not in definitions', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        // Create store without definition (using skipDefinitionSync)
-        await storeService.create(
-          {
-            name: 'orphan-store',
-            type: 'file',
-            path: docsDir,
-          },
-          { skipDefinitionSync: true }
-        );
-
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.orphans).toContain('orphan-store');
-      });
-    });
-
-    describe('dry run mode', () => {
-      it('does not create stores in dry run mode', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        await defService.addDefinition({
-          type: 'file',
-          name: 'dry-run-store',
-          path: './docs',
-        });
-
-        const result = await handleStoresSync({ dryRun: true }, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.dryRun).toBe(true);
-        expect(response.wouldCreate).toContain('dry-run-store');
-
-        // Store should NOT exist
-        const store = await storeService.getByName('dry-run-store');
-        expect(store).toBeUndefined();
-      });
-    });
-
-    describe('prune mode', () => {
-      it('removes orphan stores when prune is true', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        // Create orphan store
-        await storeService.create(
-          {
-            name: 'to-prune',
-            type: 'file',
-            path: docsDir,
-          },
-          { skipDefinitionSync: true }
-        );
-
-        const result = await handleStoresSync({ prune: true }, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.pruned).toContain('to-prune');
-
-        // Store should be deleted
-        const store = await storeService.getByName('to-prune');
-        expect(store).toBeUndefined();
-      });
-
-      it('does not prune in dry run mode', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        await storeService.create(
-          {
-            name: 'keep-me',
-            type: 'file',
-            path: docsDir,
-          },
-          { skipDefinitionSync: true }
-        );
-
-        const result = await handleStoresSync({ prune: true, dryRun: true }, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.wouldPrune).toContain('keep-me');
-
-        // Store should still exist
-        const store = await storeService.getByName('keep-me');
-        expect(store).toBeDefined();
-      });
-    });
-
-    describe('error handling', () => {
-      it('continues on error and reports failures', async () => {
-        // Add definition for non-existent directory
-        await defService.addDefinition({
-          type: 'file',
-          name: 'bad-store',
-          path: './nonexistent',
-        });
-
-        // Also add a valid definition
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-        await defService.addDefinition({
-          type: 'file',
-          name: 'good-store',
-          path: './docs',
-        });
-
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        // Should have one failure and one success
-        expect(response.failed).toHaveLength(1);
-        expect(response.failed[0].name).toBe('bad-store');
-        expect(response.failed[0].error).toBeDefined();
-        expect(response.created).toContain('good-store');
-      });
-    });
-
-    describe('empty config', () => {
-      it('handles empty definitions gracefully', async () => {
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.created).toHaveLength(0);
-        expect(response.skipped).toHaveLength(0);
-        expect(response.failed).toHaveLength(0);
-        expect(response.orphans).toHaveLength(0);
-      });
-    });
-
-    describe('reindex mode', () => {
-      it('reports wouldReindex in dry run mode', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        // Create store (auto-adds definition)
-        await storeService.create({
-          name: 'existing-store',
-          type: 'file',
-          path: docsDir,
-        });
-
-        const result = await handleStoresSync({ reindex: true, dryRun: true }, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.dryRun).toBe(true);
-        expect(response.wouldReindex).toContain('existing-store');
-        expect(response.reindexJobs).toBeUndefined();
-      });
-
-      it('starts reindex jobs for existing stores', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        // Create store (auto-adds definition)
-        await storeService.create({
-          name: 'reindex-store',
-          type: 'file',
-          path: docsDir,
-        });
-
-        const result = await handleStoresSync({ reindex: true }, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.reindexJobs).toHaveLength(1);
-        expect(response.reindexJobs[0].store).toBe('reindex-store');
-        expect(response.reindexJobs[0].jobId).toMatch(/^job_/);
-      });
-
-      it('does not reindex if reindex flag is not set', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        await storeService.create({
-          name: 'no-reindex-store',
-          type: 'file',
-          path: docsDir,
-        });
-
-        const result = await handleStoresSync({}, context);
-        const response = JSON.parse(result.content[0].text);
-
-        expect(response.reindexJobs).toBeUndefined();
-        expect(response.wouldReindex).toBeUndefined();
-      });
-
-      it('throws error when dataDir is undefined during reindex', async () => {
-        const docsDir = join(projectRoot, 'docs');
-        await mkdir(docsDir, { recursive: true });
-
-        await storeService.create({
-          name: 'error-store',
-          type: 'file',
-          path: docsDir,
-        });
-
-        // Create context without dataDir
-        const contextWithoutDataDir: HandlerContext = {
-          services: createMockServices(storeService),
-          options: { projectRoot },
-        };
-
-        await expect(handleStoresSync({ reindex: true }, contextWithoutDataDir)).rejects.toThrow(
-          'dataDir is required for reindexing'
-        );
-      });
-    });
-  });
-});