bluera-knowledge 0.10.0 → 0.11.0

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

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+import { StoreDefinitionService } from '../../services/store-definition.service.js';
+import {
+  isFileStoreDefinition,
+  isRepoStoreDefinition,
+  isWebStoreDefinition,
+} from '../../types/store-definition.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 {
+  reindex?: boolean;
+  prune?: boolean;
+  dryRun?: 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[];
+}
+
+/**
+ * Handle stores:sync command
+ *
+ * Syncs stores from definitions config:
+ * - Creates missing stores from definitions
+ * - Reports stores not in definitions (orphans)
+ * - Optionally prunes orphan stores
+ * - Optionally re-indexes existing 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);
+          }
+        }
+      }
+    }
+  }
+
+  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({
+      reindex: z.boolean().optional().describe('Re-index existing stores after sync'),
+      prune: z.boolean().optional().describe('Remove stores not in definitions'),
+      dryRun: z.boolean().optional().describe('Show what would happen without making changes'),
+    }),
+    handler: (args: Record<string, unknown>, context: HandlerContext): Promise<ToolResponse> => {
+      const syncArgs: SyncStoresArgs = {};
+      if (typeof args['reindex'] === 'boolean') {
+        syncArgs.reindex = args['reindex'];
+      }
+      if (typeof args['prune'] === 'boolean') {
+        syncArgs.prune = args['prune'];
+      }
+      if (typeof args['dryRun'] === 'boolean') {
+        syncArgs.dryRun = args['dryRun'];
+      }
+      return handleStoresSync(syncArgs, context);
+    },
+  },
+];

package/src/mcp/server.ts

@@ -1,15 +1,23 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { AdapterRegistry } from '../analysis/adapter-registry.js';
+import { ZilAdapter } from '../analysis/zil/index.js';
+import { createLogger } from '../logging/index.js';
 import { createServices } from '../services/index.js';
 import { handleExecute } from './handlers/execute.handler.js';
 import { tools } from './handlers/index.js';
 import { ExecuteArgsSchema } from './schemas/index.js';
-import { createLogger } from '../logging/index.js';
 import type { MCPServerOptions } from './types.js';
 
 const logger = createLogger('mcp-server');
 
+// Register built-in language adapters
+const registry = AdapterRegistry.getInstance();
+if (!registry.hasExtension('.zil')) {
+  registry.register(new ZilAdapter());
+}
+
 // eslint-disable-next-line @typescript-eslint/no-deprecated
 export function createMCPServer(options: MCPServerOptions): Server {
   // eslint-disable-next-line @typescript-eslint/no-deprecated

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

@@ -0,0 +1,157 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { GitignoreService } from './gitignore.service.js';
+import { rm, mkdtemp, writeFile, readFile, access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+describe('GitignoreService', () => {
+  let projectRoot: string;
+  let service: GitignoreService;
+
+  beforeEach(async () => {
+    projectRoot = await mkdtemp(join(tmpdir(), 'gitignore-test-'));
+    service = new GitignoreService(projectRoot);
+  });
+
+  afterEach(async () => {
+    await rm(projectRoot, { recursive: true, force: true });
+  });
+
+  describe('hasRequiredPatterns', () => {
+    it('returns false when .gitignore does not exist', async () => {
+      const has = await service.hasRequiredPatterns();
+      expect(has).toBe(false);
+    });
+
+    it('returns false when .gitignore exists but is empty', async () => {
+      await writeFile(join(projectRoot, '.gitignore'), '');
+      const has = await service.hasRequiredPatterns();
+      expect(has).toBe(false);
+    });
+
+    it('returns false when .gitignore is missing bluera patterns', async () => {
+      await writeFile(join(projectRoot, '.gitignore'), 'node_modules/\n*.log\n');
+      const has = await service.hasRequiredPatterns();
+      expect(has).toBe(false);
+    });
+
+    it('returns true when all required patterns are present', async () => {
+      const content = `
+node_modules/
+.bluera/
+!.bluera/bluera-knowledge/
+!.bluera/bluera-knowledge/stores.config.json
+`;
+      await writeFile(join(projectRoot, '.gitignore'), content);
+      const has = await service.hasRequiredPatterns();
+      expect(has).toBe(true);
+    });
+
+    it('returns false when only some patterns are present', async () => {
+      const content = `
+.bluera/
+`;
+      await writeFile(join(projectRoot, '.gitignore'), content);
+      const has = await service.hasRequiredPatterns();
+      expect(has).toBe(false);
+    });
+  });
+
+  describe('ensureGitignorePatterns', () => {
+    it('creates .gitignore if it does not exist', async () => {
+      const result = await service.ensureGitignorePatterns();
+
+      expect(result.updated).toBe(true);
+      expect(result.message).toContain('Created');
+
+      // Verify file exists
+      const gitignorePath = join(projectRoot, '.gitignore');
+      await expect(access(gitignorePath)).resolves.toBeUndefined();
+    });
+
+    it('adds patterns to empty .gitignore', async () => {
+      await writeFile(join(projectRoot, '.gitignore'), '');
+
+      const result = await service.ensureGitignorePatterns();
+
+      expect(result.updated).toBe(true);
+      expect(result.message).toContain('Updated');
+
+      const content = await readFile(join(projectRoot, '.gitignore'), 'utf-8');
+      expect(content).toContain('.bluera/');
+      expect(content).toContain('!.bluera/bluera-knowledge/');
+      expect(content).toContain('!.bluera/bluera-knowledge/stores.config.json');
+    });
+
+    it('appends patterns to existing .gitignore', async () => {
+      const existingContent = 'node_modules/\n*.log\n';
+      await writeFile(join(projectRoot, '.gitignore'), existingContent);
+
+      const result = await service.ensureGitignorePatterns();
+
+      expect(result.updated).toBe(true);
+
+      const content = await readFile(join(projectRoot, '.gitignore'), 'utf-8');
+      // Should preserve existing content
+      expect(content).toContain('node_modules/');
+      expect(content).toContain('*.log');
+      // Should add new patterns
+      expect(content).toContain('.bluera/');
+      expect(content).toContain('!.bluera/bluera-knowledge/');
+    });
+
+    it('skips if all patterns already present', async () => {
+      const existingContent = `
+node_modules/
+.bluera/
+!.bluera/bluera-knowledge/
+!.bluera/bluera-knowledge/stores.config.json
+`;
+      await writeFile(join(projectRoot, '.gitignore'), existingContent);
+
+      const result = await service.ensureGitignorePatterns();
+
+      expect(result.updated).toBe(false);
+      expect(result.message).toContain('already');
+    });
+
+    it('adds missing patterns when some are present', async () => {
+      const existingContent = '.bluera/\n';
+      await writeFile(join(projectRoot, '.gitignore'), existingContent);
+
+      const result = await service.ensureGitignorePatterns();
+
+      expect(result.updated).toBe(true);
+
+      const content = await readFile(join(projectRoot, '.gitignore'), 'utf-8');
+      expect(content).toContain('!.bluera/bluera-knowledge/');
+      expect(content).toContain('!.bluera/bluera-knowledge/stores.config.json');
+    });
+
+    it('includes header comment in new additions', async () => {
+      const result = await service.ensureGitignorePatterns();
+
+      expect(result.updated).toBe(true);
+
+      const content = await readFile(join(projectRoot, '.gitignore'), 'utf-8');
+      expect(content).toContain('# Bluera Knowledge');
+    });
+
+    it('preserves trailing newline', async () => {
+      const existingContent = 'node_modules/\n';
+      await writeFile(join(projectRoot, '.gitignore'), existingContent);
+
+      await service.ensureGitignorePatterns();
+
+      const content = await readFile(join(projectRoot, '.gitignore'), 'utf-8');
+      expect(content.endsWith('\n')).toBe(true);
+    });
+  });
+
+  describe('getGitignorePath', () => {
+    it('returns correct path', () => {
+      const path = service.getGitignorePath();
+      expect(path).toBe(join(projectRoot, '.gitignore'));
+    });
+  });
+});

package/src/services/gitignore.service.ts

@@ -0,0 +1,132 @@
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Required .gitignore patterns for Bluera Knowledge
+ *
+ * These patterns ensure:
+ * - The .bluera/ data directory (vector DB, cloned repos) is ignored
+ * - The stores.config.json file is NOT ignored (committed for team sharing)
+ */
+const REQUIRED_PATTERNS = [
+  '.bluera/',
+  '!.bluera/bluera-knowledge/',
+  '!.bluera/bluera-knowledge/stores.config.json',
+];
+
+/**
+ * Header comment for the gitignore section
+ */
+const SECTION_HEADER = `
+# Bluera Knowledge - data directory (not committed)
+# Store definitions at .bluera/bluera-knowledge/stores.config.json ARE committed for team sharing
+`;
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Service for managing .gitignore patterns for Bluera Knowledge.
+ *
+ * When stores are created, this service ensures the project's .gitignore
+ * is updated to:
+ * - Ignore the .bluera/ data directory (not committed)
+ * - Allow committing .bluera/bluera-knowledge/stores.config.json (for team sharing)
+ */
+export class GitignoreService {
+  private readonly gitignorePath: string;
+
+  constructor(projectRoot: string) {
+    this.gitignorePath = join(projectRoot, '.gitignore');
+  }
+
+  /**
+   * Check if all required patterns are present in .gitignore
+   */
+  async hasRequiredPatterns(): Promise<boolean> {
+    const exists = await fileExists(this.gitignorePath);
+    if (!exists) {
+      return false;
+    }
+
+    const content = await readFile(this.gitignorePath, 'utf-8');
+    const lines = content.split('\n').map((l) => l.trim());
+
+    for (const pattern of REQUIRED_PATTERNS) {
+      if (!lines.includes(pattern)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Ensure required .gitignore patterns are present.
+   *
+   * - Creates .gitignore if it doesn't exist
+   * - Appends missing patterns if .gitignore exists
+   * - Does nothing if all patterns are already present
+   *
+   * @returns Object with updated flag and descriptive message
+   */
+  async ensureGitignorePatterns(): Promise<{ updated: boolean; message: string }> {
+    const exists = await fileExists(this.gitignorePath);
+
+    if (!exists) {
+      // Create new .gitignore with our patterns
+      const content = `${SECTION_HEADER.trim()}\n${REQUIRED_PATTERNS.join('\n')}\n`;
+      await writeFile(this.gitignorePath, content);
+      return {
+        updated: true,
+        message: 'Created .gitignore with Bluera Knowledge patterns',
+      };
+    }
+
+    // Read existing content
+    const existingContent = await readFile(this.gitignorePath, 'utf-8');
+    const lines = existingContent.split('\n').map((l) => l.trim());
+
+    // Find missing patterns
+    const missingPatterns = REQUIRED_PATTERNS.filter((pattern) => !lines.includes(pattern));
+
+    if (missingPatterns.length === 0) {
+      return {
+        updated: false,
+        message: 'All Bluera Knowledge patterns already present in .gitignore',
+      };
+    }
+
+    // Append missing patterns
+    let newContent = existingContent;
+    if (!newContent.endsWith('\n')) {
+      newContent += '\n';
+    }
+
+    newContent += SECTION_HEADER;
+    newContent += `${missingPatterns.join('\n')}\n`;
+
+    await writeFile(this.gitignorePath, newContent);
+
+    return {
+      updated: true,
+      message: `Updated .gitignore with ${String(missingPatterns.length)} Bluera Knowledge pattern(s)`,
+    };
+  }
+
+  /**
+   * Get the path to the .gitignore file
+   */
+  getGitignorePath(): string {
+    return this.gitignorePath;
+  }
+}