bluera-knowledge 0.9.38 → 0.9.40

package/dist/mcp/server.js

@@ -1,8 +1,8 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-36IFANFI.js";
-import "../chunk-XJFV7AJW.js";
+} from "../chunk-TIGPI3BE.js";
+import "../chunk-HUEWT6U5.js";
 import "../chunk-6FHWC36B.js";
 export {
   createMCPServer,

package/dist/workers/background-worker-cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   IntelligentCrawler
-} from "../chunk-ZAWIPEYX.js";
+} from "../chunk-IZWOEBFM.js";
 import {
   JobService,
   createDocumentId,
   createServices,
   createStoreId
-} from "../chunk-XJFV7AJW.js";
+} from "../chunk-HUEWT6U5.js";
 import "../chunk-6FHWC36B.js";
 
 // src/workers/background-worker.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.9.38",
+  "version": "0.9.40",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {
@@ -28,13 +28,14 @@
     "lint:quiet": "eslint src/ --quiet && echo '✓ Lint passed' || { echo '❌ ESLint errors'; exit 1; }",
     "lint:deadcode:quiet": "knip --no-exit-code --quiet 2>&1 | grep -E '^(Unused|Configuration)' || echo '✓ No unused code'",
     "typecheck:quiet": "tsc --noEmit --pretty false && echo '✓ Type check passed'",
-    "test:changed:quiet": "vitest run --changed --reporter=dot --silent 2>&1 | tail -3",
-    "test:coverage:quiet": "vitest run --coverage --reporter=dot 2>&1 | grep -E '(FAIL|Test Files|passed|Coverage|threshold)' | tail -10",
+    "test:changed:quiet": "bash -c 'set -o pipefail && vitest run --changed --reporter=dot --silent 2>&1 | tail -3'",
+    "test:coverage:quiet": "bash -c 'set -o pipefail && vitest run --coverage --reporter=dot 2>&1 | grep -E \"(FAIL|Test Files|passed|Coverage|threshold)\" | tail -10'",
     "build:quiet": "tsup --silent && echo '✓ Build complete'",
+    "prerelease": "bun run format:check:quiet && bun run lint:quiet && bun run lint:deadcode:quiet && bun run typecheck:quiet && bun run test:coverage:quiet && bun run build:quiet",
     "prepare": "husky",
-    "version:major": "commit-and-tag-version --release-as major --skip.commit --skip.tag",
-    "version:minor": "commit-and-tag-version --release-as minor --skip.commit --skip.tag",
-    "version:patch": "commit-and-tag-version --release-as patch --skip.commit --skip.tag",
+    "version:major": "bun run prerelease && commit-and-tag-version --release-as major --skip.commit --skip.tag",
+    "version:minor": "bun run prerelease && commit-and-tag-version --release-as minor --skip.commit --skip.tag",
+    "version:patch": "bun run prerelease && commit-and-tag-version --release-as patch --skip.commit --skip.tag",
     "release:patch": "commit-and-tag-version --release-as patch && git push --follow-tags",
     "release:minor": "commit-and-tag-version --release-as minor && git push --follow-tags",
     "release:major": "commit-and-tag-version --release-as major && git push --follow-tags"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.9.38",
+  "version": "0.9.40",
   "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
   "commands": "./commands",
   "hooks": "./hooks/hooks.json",

package/src/cli/commands/search.ts

@@ -18,6 +18,10 @@ export function createSearchCommand(getOptions: () => GlobalOptions): Command {
     )
     .option('-n, --limit <count>', 'Maximum results to return (default: 10)', '10')
     .option('-t, --threshold <score>', 'Minimum score 0-1; omit low-relevance results')
+    .option(
+      '--min-relevance <score>',
+      'Minimum raw cosine similarity 0-1; returns empty if no results meet threshold'
+    )
     .option('--include-content', 'Show full document content, not just preview snippet')
     .option(
       '--detail <level>',
@@ -32,6 +36,7 @@ export function createSearchCommand(getOptions: () => GlobalOptions): Command {
           mode?: SearchMode;
           limit?: string;
           threshold?: string;
+          minRelevance?: string;
           includeContent?: boolean;
           detail?: DetailLevel;
         }
@@ -82,6 +87,8 @@ export function createSearchCommand(getOptions: () => GlobalOptions): Command {
               limit: parseInt(options.limit ?? '10', 10),
               threshold:
                 options.threshold !== undefined ? parseFloat(options.threshold) : undefined,
+              minRelevance:
+                options.minRelevance !== undefined ? parseFloat(options.minRelevance) : undefined,
               includeContent: options.includeContent,
               detail: options.detail ?? 'minimal',
             });
@@ -96,12 +103,23 @@ export function createSearchCommand(getOptions: () => GlobalOptions): Command {
               }
             } else {
               console.log(`\nSearch: "${query}"`);
-              console.log(
-                `Mode: ${results.mode} | Detail: ${String(options.detail)} | Stores: ${String(results.stores.length)} | Results: ${String(results.totalResults)} | Time: ${String(results.timeMs)}ms\n`
-              );
+
+              // Build status line with optional confidence info
+              let statusLine = `Mode: ${results.mode} | Detail: ${String(options.detail)} | Stores: ${String(results.stores.length)} | Results: ${String(results.totalResults)} | Time: ${String(results.timeMs)}ms`;
+              if (results.confidence !== undefined) {
+                statusLine += ` | Confidence: ${results.confidence}`;
+              }
+              if (results.maxRawScore !== undefined) {
+                statusLine += ` | MaxRaw: ${results.maxRawScore.toFixed(3)}`;
+              }
+              console.log(`${statusLine}\n`);
 
               if (results.results.length === 0) {
-                console.log('No results found.\n');
+                if (results.confidence === 'low') {
+                  console.log('No sufficiently relevant results found.\n');
+                } else {
+                  console.log('No results found.\n');
+                }
               } else {
                 for (let i = 0; i < results.results.length; i++) {
                   const r = results.results[i];

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

@@ -72,6 +72,7 @@ export const handleSearch: ToolHandler<SearchArgs> = async (
     mode: 'hybrid',
     limit: validated.limit,
     detail: validated.detail,
+    minRelevance: validated.minRelevance,
   };
 
   const results = await services.search.search(searchQuery);
@@ -107,6 +108,8 @@ export const handleSearch: ToolHandler<SearchArgs> = async (
       totalResults: results.totalResults,
       mode: results.mode,
       timeMs: results.timeMs,
+      confidence: results.confidence,
+      maxRawScore: results.maxRawScore,
     },
     null,
     2
@@ -115,8 +118,10 @@ export const handleSearch: ToolHandler<SearchArgs> = async (
   // Calculate actual token estimate based on response content
   const responseTokens = estimateTokens(responseJson);
 
-  // Create visible header with token usage
-  const header = `Search: "${validated.query}" | Results: ${String(results.totalResults)} | ${formatTokenCount(responseTokens)} tokens | ${String(results.timeMs)}ms\n\n`;
+  // Create visible header with token usage and confidence
+  const confidenceInfo =
+    results.confidence !== undefined ? ` | Confidence: ${results.confidence}` : '';
+  const header = `Search: "${validated.query}" | Results: ${String(results.totalResults)} | ${formatTokenCount(responseTokens)} tokens | ${String(results.timeMs)}ms${confidenceInfo}\n\n`;
 
   // Log the complete MCP response that will be sent to Claude Code
   logger.info(

package/src/mcp/schemas/index.ts

@@ -28,6 +28,11 @@ export const SearchArgsSchema = z.object({
   detail: z.enum(['minimal', 'contextual', 'full']).default('minimal'),
   limit: z.number().int().positive().default(10),
   stores: z.array(z.string()).optional(),
+  minRelevance: z
+    .number()
+    .min(0, 'minRelevance must be between 0 and 1')
+    .max(1, 'minRelevance must be between 0 and 1')
+    .optional(),
 });
 
 export type SearchArgs = z.infer<typeof SearchArgsSchema>;

package/src/mcp/server.ts

@@ -70,6 +70,11 @@ export function createMCPServer(options: MCPServerOptions): Server {
                 items: { type: 'string' },
                 description: 'Specific store IDs to search (optional)',
               },
+              minRelevance: {
+                type: 'number',
+                description:
+                  'Minimum raw cosine similarity (0-1). Returns empty if no results meet threshold. Use to filter irrelevant results.',
+              },
             },
             required: ['query'],
           },

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

@@ -1161,6 +1161,7 @@ describe('SearchService - Edge Cases', () => {
   });
 
   it('handles threshold parameter for vector search', async () => {
+    // Setup: multiple results with varying scores
     vi.mocked(mockLanceStore.search).mockResolvedValue([
       {
         id: createDocumentId('doc1'),
@@ -1168,22 +1169,41 @@ describe('SearchService - Edge Cases', () => {
         content: 'high score',
         metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
       },
+      {
+        id: createDocumentId('doc2'),
+        score: 0.5,
+        content: 'medium score',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+      {
+        id: createDocumentId('doc3'),
+        score: 0.3,
+        content: 'low score',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
     ]);
 
+    // Search with high threshold
     const results = await searchService.search({
       query: 'test',
       stores: [storeId],
       mode: 'vector',
       limit: 10,
-      threshold: 0.9,
+      threshold: 0.8,
     });
 
+    // Verify lanceStore.search was called (without checking threshold param - it's unused in LanceStore)
     expect(vi.mocked(mockLanceStore.search)).toHaveBeenCalledWith(
       storeId,
       expect.anything(),
-      expect.anything(),
-      0.9
+      expect.anything()
     );
+
+    // Verify threshold filtering works: only high-score result should pass
+    // After normalization, the top result has score 1.0, and threshold 0.8 filters out lower ones
+    // The normalized scores are: doc1=1.0, doc2=0.31, doc3=0.0 (relative to max 0.95)
+    expect(results.results.length).toBe(1);
+    expect(results.results[0]?.id).toBe('doc1');
   });
 });
 
@@ -1992,3 +2012,171 @@ describe('SearchService - Threshold Filtering', () => {
     expect(results.query).toBe('test query');
   });
 });
+
+describe('SearchService - Raw Score and Confidence', () => {
+  let mockLanceStore: LanceStore;
+  let mockEmbeddingEngine: EmbeddingEngine;
+  let searchService: SearchService;
+  const storeId = createStoreId('test-store');
+
+  beforeEach(() => {
+    mockLanceStore = {
+      search: vi.fn(),
+      fullTextSearch: vi.fn(),
+    } as unknown as LanceStore;
+
+    mockEmbeddingEngine = {
+      embed: vi.fn().mockResolvedValue([0.1, 0.2, 0.3]),
+    } as unknown as EmbeddingEngine;
+
+    searchService = new SearchService(mockLanceStore, mockEmbeddingEngine);
+  });
+
+  it('exposes rawVectorScore in rankingMetadata for hybrid search', async () => {
+    // Mock results with known raw vector scores
+    vi.mocked(mockLanceStore.search).mockResolvedValue([
+      {
+        id: createDocumentId('doc1'),
+        score: 0.85, // Raw cosine similarity
+        content: 'vector result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+      {
+        id: createDocumentId('doc2'),
+        score: 0.65,
+        content: 'another vector result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+    ]);
+    vi.mocked(mockLanceStore.fullTextSearch).mockResolvedValue([]);
+
+    const results = await searchService.search({
+      query: 'test query',
+      stores: [storeId],
+      mode: 'hybrid',
+      limit: 10,
+    });
+
+    // Verify results have rawVectorScore in rankingMetadata
+    expect(results.results.length).toBeGreaterThan(0);
+    const firstResult = results.results[0];
+    expect(firstResult?.rankingMetadata).toBeDefined();
+    expect(firstResult?.rankingMetadata?.rawVectorScore).toBeDefined();
+    expect(firstResult?.rankingMetadata?.rawVectorScore).toBe(0.85);
+  });
+
+  it('returns confidence level based on maxRawScore', async () => {
+    // Mock results with high raw vector score (>= 0.5)
+    vi.mocked(mockLanceStore.search).mockResolvedValue([
+      {
+        id: createDocumentId('doc1'),
+        score: 0.6, // High confidence threshold
+        content: 'high score result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+    ]);
+    vi.mocked(mockLanceStore.fullTextSearch).mockResolvedValue([]);
+
+    const results = await searchService.search({
+      query: 'test query',
+      stores: [storeId],
+      mode: 'hybrid',
+      limit: 10,
+    });
+
+    expect(results.confidence).toBe('high');
+    expect(results.maxRawScore).toBe(0.6);
+  });
+
+  it('returns medium confidence for scores between 0.3 and 0.5', async () => {
+    vi.mocked(mockLanceStore.search).mockResolvedValue([
+      {
+        id: createDocumentId('doc1'),
+        score: 0.4, // Medium confidence
+        content: 'medium score result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+    ]);
+    vi.mocked(mockLanceStore.fullTextSearch).mockResolvedValue([]);
+
+    const results = await searchService.search({
+      query: 'test query',
+      stores: [storeId],
+      mode: 'hybrid',
+      limit: 10,
+    });
+
+    expect(results.confidence).toBe('medium');
+    expect(results.maxRawScore).toBe(0.4);
+  });
+
+  it('returns low confidence for scores below 0.3', async () => {
+    vi.mocked(mockLanceStore.search).mockResolvedValue([
+      {
+        id: createDocumentId('doc1'),
+        score: 0.2, // Low confidence
+        content: 'low score result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+    ]);
+    vi.mocked(mockLanceStore.fullTextSearch).mockResolvedValue([]);
+
+    const results = await searchService.search({
+      query: 'test query',
+      stores: [storeId],
+      mode: 'hybrid',
+      limit: 10,
+    });
+
+    expect(results.confidence).toBe('low');
+    expect(results.maxRawScore).toBe(0.2);
+  });
+
+  it('filters results with minRelevance based on raw score', async () => {
+    vi.mocked(mockLanceStore.search).mockResolvedValue([
+      {
+        id: createDocumentId('doc1'),
+        score: 0.25, // Below minRelevance threshold
+        content: 'low relevance result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+    ]);
+    vi.mocked(mockLanceStore.fullTextSearch).mockResolvedValue([]);
+
+    const results = await searchService.search({
+      query: 'irrelevant query',
+      stores: [storeId],
+      mode: 'hybrid',
+      limit: 10,
+      minRelevance: 0.4, // Filter out results below this raw score
+    });
+
+    // Should return empty since max raw score (0.25) < minRelevance (0.4)
+    expect(results.results.length).toBe(0);
+    expect(results.confidence).toBe('low');
+  });
+
+  it('returns results when maxRawScore meets minRelevance', async () => {
+    vi.mocked(mockLanceStore.search).mockResolvedValue([
+      {
+        id: createDocumentId('doc1'),
+        score: 0.5, // Above minRelevance threshold
+        content: 'relevant result',
+        metadata: { type: 'file' as const, storeId, indexedAt: new Date() },
+      },
+    ]);
+    vi.mocked(mockLanceStore.fullTextSearch).mockResolvedValue([]);
+
+    const results = await searchService.search({
+      query: 'relevant query',
+      stores: [storeId],
+      mode: 'hybrid',
+      limit: 10,
+      minRelevance: 0.4,
+    });
+
+    // Should return results since max raw score (0.5) >= minRelevance (0.4)
+    expect(results.results.length).toBe(1);
+    expect(results.confidence).toBe('high');
+  });
+});