bluera-knowledge 0.11.20 → 0.12.1

package/src/cli/commands/store.ts

@@ -1,3 +1,5 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
 import { Command } from 'commander';
 import { createServices, destroyServices } from '../../services/index.js';
 import type { StoreType } from '../../types/store.js';
@@ -49,6 +51,7 @@ export function createStoreCommand(getOptions: () => GlobalOptions): Command {
       'Store type: file (local dir), repo (git), web (crawled site)'
     )
     .requiredOption('-s, --source <path>', 'Local path for file/repo stores, URL for web stores')
+    .option('-b, --branch <branch>', 'Git branch to clone (repo stores only)')
     .option('-d, --description <desc>', 'Optional description for the store')
     .option('--tags <tags>', 'Comma-separated tags for filtering')
     .action(
@@ -57,6 +60,7 @@ export function createStoreCommand(getOptions: () => GlobalOptions): Command {
         options: {
           type: StoreType;
           source: string;
+          branch?: string;
           description?: string;
           tags?: string;
         }
@@ -79,6 +83,7 @@ export function createStoreCommand(getOptions: () => GlobalOptions): Command {
               options.type === 'web' || (options.type === 'repo' && isUrl)
                 ? options.source
                 : undefined,
+            branch: options.type === 'repo' ? options.branch : undefined,
             description: options.description,
             tags: options.tags?.split(',').map((t) => t.trim()),
           });
@@ -188,6 +193,20 @@ export function createStoreCommand(getOptions: () => GlobalOptions): Command {
           }
         }
 
+        // Delete LanceDB table first (so searches don't return results for deleted store)
+        await services.lance.deleteStore(s.id);
+
+        // Delete code graph file
+        await services.codeGraph.deleteGraph(s.id);
+
+        // For repo stores cloned from URL, remove the cloned directory
+        if (s.type === 'repo' && 'url' in s && s.url !== undefined) {
+          const dataDir = services.config.resolveDataDir();
+          const repoPath = join(dataDir, 'repos', s.id);
+          await rm(repoPath, { recursive: true, force: true });
+        }
+
+        // Delete from registry last
         const result = await services.store.delete(s.id);
 
         if (result.success) {

package/src/cli/commands/sync.test.ts

@@ -49,6 +49,6 @@ describe('createSyncCommand', () => {
     expect(pruneOpt?.description).toContain('Remove');
 
     const reindexOpt = options.find((o) => o.long === '--reindex');
-    expect(reindexOpt?.description).toContain('index');
+    expect(reindexOpt?.description).toContain('Re-index');
   });
 });

package/src/cli/commands/sync.ts

@@ -1,11 +1,13 @@
 import { Command } from 'commander';
 import { createServices, destroyServices } from '../../services/index.js';
+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 { StoreService } from '../../services/store.service.js';
 import type { StoreDefinition } from '../../types/store-definition.js';
 import type { GlobalOptions } from '../program.js';
@@ -19,6 +21,8 @@ interface SyncResult {
   dryRun: boolean;
   wouldCreate: string[];
   wouldPrune: string[];
+  reindexJobs: Array<{ store: string; jobId: string }>;
+  wouldReindex: string[];
 }
 
 /**
@@ -125,6 +129,8 @@ export function createSyncCommand(getOptions: () => GlobalOptions): Command {
           dryRun: options.dryRun === true,
           wouldCreate: [],
           wouldPrune: [],
+          reindexJobs: [],
+          wouldReindex: [],
         };
 
         // Process each definition
@@ -173,6 +179,29 @@ export function createSyncCommand(getOptions: () => GlobalOptions): Command {
           }
         }
 
+        // Re-index existing stores if requested
+        if (options.reindex === true && result.skipped.length > 0) {
+          if (options.dryRun === true) {
+            result.wouldReindex = [...result.skipped];
+          } else {
+            const dataDir = globalOpts.dataDir ?? services.config.resolveDataDir();
+            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 });
+              }
+            }
+          }
+        }
+
         // Output result
         if (globalOpts.format === 'json') {
           console.log(JSON.stringify(result, null, 2));
@@ -189,19 +218,25 @@ export function createSyncCommand(getOptions: () => GlobalOptions): Command {
 
 function printHumanReadable(result: SyncResult, quiet: boolean): void {
   if (quiet) {
-    // Just print created/pruned store names
+    // Just print created/pruned/reindexed store names
     for (const name of result.created) {
       console.log(`created: ${name}`);
     }
     for (const name of result.pruned) {
       console.log(`pruned: ${name}`);
     }
+    for (const { store, jobId } of result.reindexJobs) {
+      console.log(`reindexing: ${store} (${jobId})`);
+    }
     for (const name of result.wouldCreate) {
       console.log(`would create: ${name}`);
     }
     for (const name of result.wouldPrune) {
       console.log(`would prune: ${name}`);
     }
+    for (const name of result.wouldReindex) {
+      console.log(`would reindex: ${name}`);
+    }
     return;
   }
 
@@ -260,5 +295,19 @@ function printHumanReadable(result: SyncResult, quiet: boolean): void {
     }
   }
 
+  if (result.reindexJobs.length > 0) {
+    console.log(`Reindexing started (${String(result.reindexJobs.length)}):`);
+    for (const { store, jobId } of result.reindexJobs) {
+      console.log(`  ↻ ${store} (Job: ${jobId})`);
+    }
+  }
+
+  if (result.wouldReindex.length > 0) {
+    console.log(`Would reindex (${String(result.wouldReindex.length)}):`);
+    for (const name of result.wouldReindex) {
+      console.log(`  ↻ ${name}`);
+    }
+  }
+
   console.log('');
 }

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

@@ -1,6 +1,5 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { z } from 'zod';
-import { rm, mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+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';
@@ -8,7 +7,11 @@ 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';
-import type { StoreDefinitionsConfig } from '../../types/store-definition.js';
+
+// Mock spawnBackgroundWorker
+vi.mock('../../workers/spawn-worker.js', () => ({
+  spawnBackgroundWorker: vi.fn(),
+}));
 
 /**
  * Create a minimal mock service container for testing
@@ -45,11 +48,18 @@ describe('sync.commands', () => {
 
       // Valid with options
       const result2 = syncCmd?.argsSchema?.safeParse({
-        reindex: true,
         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);
     });
   });
 
@@ -69,7 +79,7 @@ describe('sync.commands', () => {
 
       context = {
         services: createMockServices(storeService),
-        options: { projectRoot },
+        options: { projectRoot, dataDir },
       };
     });
 
@@ -279,5 +289,83 @@ describe('sync.commands', () => {
         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'
+        );
+      });
+    });
   });
 });

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

@@ -1,10 +1,12 @@
 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';
@@ -13,9 +15,9 @@ import type { HandlerContext, ToolResponse } from '../types.js';
  * Arguments for stores:sync command
  */
 export interface SyncStoresArgs {
-  reindex?: boolean;
   prune?: boolean;
   dryRun?: boolean;
+  reindex?: boolean;
 }
 
 /**
@@ -30,6 +32,8 @@ interface SyncResult {
   dryRun?: boolean;
   wouldCreate?: string[];
   wouldPrune?: string[];
+  reindexJobs?: Array<{ store: string; jobId: string }>;
+  wouldReindex?: string[];
 }
 
 /**
@@ -39,7 +43,6 @@ interface SyncResult {
  * - 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,
@@ -119,6 +122,33 @@ export async function handleStoresSync(
     }
   }
 
+  // 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: [
       {
@@ -212,21 +242,21 @@ 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'),
+      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['reindex'] === 'boolean') {
-        syncArgs.reindex = args['reindex'];
-      }
       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/search.handler.ts

@@ -30,6 +30,7 @@ export const handleSearch: ToolHandler<SearchArgs> = async (
     {
       query: validated.query,
       stores: validated.stores,
+      mode: validated.mode,
       detail: validated.detail,
       limit: validated.limit,
       intent: validated.intent,
@@ -69,9 +70,10 @@ export const handleSearch: ToolHandler<SearchArgs> = async (
   const searchQuery: SearchQuery = {
     query: validated.query,
     stores: storeIds,
-    mode: 'hybrid',
+    mode: validated.mode,
     limit: validated.limit,
     detail: validated.detail,
+    threshold: validated.threshold,
     minRelevance: validated.minRelevance,
   };
 

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

@@ -42,6 +42,9 @@ describe('store.handler', () => {
         lance: {
           deleteStore: vi.fn().mockResolvedValue(undefined),
         },
+        codeGraph: {
+          deleteGraph: vi.fn().mockResolvedValue(undefined),
+        },
       } as any,
       options: { dataDir: tempDir },
     };

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

@@ -274,9 +274,12 @@ export const handleDeleteStore: ToolHandler<DeleteStoreArgs> = async (
     throw new Error(`Store not found: ${validated.store}`);
   }
 
-  // Delete LanceDB table
+  // Delete LanceDB table first (so searches don't return results for deleted store)
   await services.lance.deleteStore(store.id);
 
+  // Delete code graph file
+  await services.codeGraph.deleteGraph(store.id);
+
   // For repo stores cloned from URL, remove the cloned directory
   if (store.type === 'repo' && 'url' in store && store.url !== undefined) {
     if (options.dataDir === undefined) {
@@ -286,7 +289,7 @@ export const handleDeleteStore: ToolHandler<DeleteStoreArgs> = async (
     await rm(repoPath, { recursive: true, force: true });
   }
 
-  // Delete from registry
+  // Delete from registry last
   const result = await services.store.delete(store.id);
   if (!result.success) {
     throw new Error(result.error.message);

package/src/mcp/schemas/index.test.ts

@@ -29,10 +29,46 @@ describe('MCP Schema Validation', () => {
     it('should use defaults for optional fields', () => {
       const result = SearchArgsSchema.parse({ query: 'test' });
 
+      expect(result.mode).toBe('hybrid');
       expect(result.detail).toBe('minimal');
       expect(result.limit).toBe(10);
     });
 
+    it('should validate mode enum', () => {
+      expect(() => SearchArgsSchema.parse({ query: 'test', mode: 'invalid' })).toThrow();
+
+      const vector = SearchArgsSchema.parse({ query: 'test', mode: 'vector' });
+      expect(vector.mode).toBe('vector');
+
+      const fts = SearchArgsSchema.parse({ query: 'test', mode: 'fts' });
+      expect(fts.mode).toBe('fts');
+
+      const hybrid = SearchArgsSchema.parse({ query: 'test', mode: 'hybrid' });
+      expect(hybrid.mode).toBe('hybrid');
+    });
+
+    it('should validate threshold', () => {
+      const result = SearchArgsSchema.parse({ query: 'test', threshold: 0.5 });
+      expect(result.threshold).toBe(0.5);
+
+      // Edge cases
+      const min = SearchArgsSchema.parse({ query: 'test', threshold: 0 });
+      expect(min.threshold).toBe(0);
+
+      const max = SearchArgsSchema.parse({ query: 'test', threshold: 1 });
+      expect(max.threshold).toBe(1);
+    });
+
+    it('should reject invalid threshold', () => {
+      expect(() => SearchArgsSchema.parse({ query: 'test', threshold: -0.1 })).toThrow(
+        'threshold must be between 0 and 1'
+      );
+
+      expect(() => SearchArgsSchema.parse({ query: 'test', threshold: 1.1 })).toThrow(
+        'threshold must be between 0 and 1'
+      );
+    });
+
     it('should reject empty query', () => {
       expect(() => SearchArgsSchema.parse({ query: '' })).toThrow(
         'Query must be a non-empty string'

package/src/mcp/schemas/index.ts

@@ -25,9 +25,15 @@ export const SearchArgsSchema = z.object({
       'find-documentation',
     ])
     .optional(),
+  mode: z.enum(['vector', 'fts', 'hybrid']).default('hybrid'),
   detail: z.enum(['minimal', 'contextual', 'full']).default('minimal'),
   limit: z.number().int().positive().default(10),
   stores: z.array(z.string()).optional(),
+  threshold: z
+    .number()
+    .min(0, 'threshold must be between 0 and 1')
+    .max(1, 'threshold must be between 0 and 1')
+    .optional(),
   minRelevance: z
     .number()
     .min(0, 'minRelevance must be between 0 and 1')

package/src/mcp/server.ts

@@ -61,6 +61,13 @@ export function createMCPServer(options: MCPServerOptions): Server {
                 ],
                 description: 'Search intent for better ranking',
               },
+              mode: {
+                type: 'string',
+                enum: ['vector', 'fts', 'hybrid'],
+                default: 'hybrid',
+                description:
+                  'Search mode: vector (embeddings only), fts (full-text only), hybrid (both, default)',
+              },
               detail: {
                 type: 'string',
                 enum: ['minimal', 'contextual', 'full'],
@@ -78,6 +85,10 @@ export function createMCPServer(options: MCPServerOptions): Server {
                 items: { type: 'string' },
                 description: 'Specific store IDs to search (optional)',
               },
+              threshold: {
+                type: 'number',
+                description: 'Minimum normalized score (0-1). Filters out low-relevance results.',
+              },
               minRelevance: {
                 type: 'number',
                 description:

package/src/services/code-graph.service.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { ASTParser } from '../analysis/ast-parser.js';
 import { CodeGraph, type GraphNode } from '../analysis/code-graph.js';
@@ -120,6 +120,16 @@ export class CodeGraphService {
     await writeFile(graphPath, JSON.stringify(serialized, null, 2));
   }
 
+  /**
+   * Delete the code graph file for a store.
+   * Silently succeeds if the file doesn't exist.
+   */
+  async deleteGraph(storeId: StoreId): Promise<void> {
+    const graphPath = this.getGraphPath(storeId);
+    await rm(graphPath, { force: true });
+    this.graphCache.delete(storeId);
+  }
+
   /**
    * Load a code graph for a store.
    * Returns undefined if no graph exists.

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

@@ -24,6 +24,29 @@ describe('JobService', () => {
       const jobsDir = join(tempDir, 'jobs');
       expect(existsSync(jobsDir)).toBe(true);
     });
+
+    it('throws when dataDir not provided and HOME/USERPROFILE undefined', () => {
+      const originalHome = process.env['HOME'];
+      const originalUserProfile = process.env['USERPROFILE'];
+
+      try {
+        delete process.env['HOME'];
+        delete process.env['USERPROFILE'];
+
+        // Should throw instead of falling back to current directory
+        expect(() => new JobService()).toThrow(
+          'HOME or USERPROFILE environment variable is required'
+        );
+      } finally {
+        // Restore environment
+        if (originalHome !== undefined) {
+          process.env['HOME'] = originalHome;
+        }
+        if (originalUserProfile !== undefined) {
+          process.env['USERPROFILE'] = originalUserProfile;
+        }
+      }
+    });
   });
 
   describe('createJob', () => {

package/src/services/job.service.ts

@@ -9,12 +9,16 @@ export class JobService {
 
   constructor(dataDir?: string) {
     // Default to ~/.local/share/bluera-knowledge/jobs
-    const baseDir =
-      dataDir ??
-      path.join(
-        process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.',
-        '.local/share/bluera-knowledge'
-      );
+    let baseDir: string;
+    if (dataDir !== undefined) {
+      baseDir = dataDir;
+    } else {
+      const homeDir = process.env['HOME'] ?? process.env['USERPROFILE'];
+      if (homeDir === undefined) {
+        throw new Error('HOME or USERPROFILE environment variable is required');
+      }
+      baseDir = path.join(homeDir, '.local/share/bluera-knowledge');
+    }
     this.jobsDir = path.join(baseDir, 'jobs');
 
     // Ensure jobs directory exists