@sylphx/flow 1.0.1 → 1.0.3

package/src/services/search/unified-search-service.ts

@@ -0,0 +1,888 @@
+/**
+ * Unified Search Service
+ * Shared search logic for CLI, MCP, and API
+ */
+
+import { filter, map, pipe, take } from '../../utils/functional.js';
+import { SeparatedMemoryStorage } from '../storage/separated-storage.js';
+import { CodebaseIndexer } from './codebase-indexer.js';
+import type { EmbeddingProvider } from './embeddings.js';
+import { getDefaultEmbeddingProvider } from './embeddings.js';
+import { getKnowledgeIndexer } from './knowledge-indexer.js';
+import { searchDocuments } from './tfidf.js';
+
+export interface SearchResult {
+  uri: string;
+  score: number;
+  title?: string;
+  content?: string;
+  metadata?: any;
+}
+
+export interface SearchOptions {
+  limit?: number;
+  include_content?: boolean;
+  file_extensions?: string[];
+  path_filter?: string;
+  exclude_paths?: string[];
+  min_score?: number;
+}
+
+export interface SearchStatus {
+  codebase: {
+    indexed: boolean;
+    fileCount: number;
+    indexedAt?: string;
+    isIndexing?: boolean;
+    progress?: number;
+    currentFile?: string;
+  };
+  knowledge: {
+    indexed: boolean;
+    documentCount: number;
+    isIndexing?: boolean;
+    progress?: number;
+  };
+}
+
+/**
+ * Dependencies for UnifiedSearchService
+ * Allows dependency injection for testing and flexibility
+ */
+export interface SearchServiceDependencies {
+  readonly memoryStorage?: SeparatedMemoryStorage;
+  readonly knowledgeIndexer?: ReturnType<typeof getKnowledgeIndexer>;
+  readonly codebaseIndexer?: CodebaseIndexer;
+  readonly embeddingProvider?: EmbeddingProvider;
+}
+
+/**
+ * UnifiedSearchService Interface
+ * Public API for search operations
+ */
+export interface UnifiedSearchService {
+  readonly initialize: () => Promise<void>;
+  readonly getStatus: () => Promise<SearchStatus>;
+  readonly searchCodebase: (
+    query: string,
+    options?: SearchOptions
+  ) => Promise<{
+    results: SearchResult[];
+    totalIndexed: number;
+    query: string;
+  }>;
+  readonly searchKnowledge: (
+    query: string,
+    options?: SearchOptions
+  ) => Promise<{
+    results: SearchResult[];
+    totalIndexed: number;
+    query: string;
+  }>;
+  readonly formatResultsForCLI: (
+    results: SearchResult[],
+    query: string,
+    totalIndexed: number
+  ) => string;
+  readonly formatResultsForMCP: (
+    results: SearchResult[],
+    query: string,
+    totalIndexed: number
+  ) => {
+    content: Array<{ type: 'text'; text: string }>;
+  };
+  readonly getAvailableKnowledgeURIs: () => Promise<string[]>;
+  readonly startCodebaseWatching: () => void;
+  readonly stopCodebaseWatching: () => void;
+}
+
+/**
+ * Internal state for UnifiedSearchService
+ */
+interface UnifiedSearchServiceState {
+  readonly memoryStorage: SeparatedMemoryStorage;
+  knowledgeIndexer: ReturnType<typeof getKnowledgeIndexer>;
+  codebaseIndexer?: CodebaseIndexer;
+  embeddingProvider?: EmbeddingProvider;
+}
+
+/**
+ * Create Unified Search Service (Factory Function)
+ * Shared search logic for CLI, MCP, and API
+ */
+export const createUnifiedSearchService = (
+  dependencies: SearchServiceDependencies = {}
+): UnifiedSearchService => {
+  // Mutable state in closure (updated immutably where possible)
+  const state: UnifiedSearchServiceState = {
+    memoryStorage: dependencies.memoryStorage || new SeparatedMemoryStorage(),
+    knowledgeIndexer: dependencies.knowledgeIndexer || getKnowledgeIndexer(),
+    codebaseIndexer: dependencies.codebaseIndexer,
+    embeddingProvider: dependencies.embeddingProvider,
+  };
+
+  /**
+   * Initialize search service
+   */
+  const initialize = async (): Promise<void> => {
+    await state.memoryStorage.initialize();
+
+    // Initialize embedding provider only if API key exists
+    if (!state.embeddingProvider && process.env.OPENAI_API_KEY) {
+      state.embeddingProvider = await getDefaultEmbeddingProvider();
+    }
+
+    // Reinitialize knowledge indexer with embedding provider (or undefined)
+    state.knowledgeIndexer = getKnowledgeIndexer(state.embeddingProvider);
+  };
+
+  /**
+   * Get search status
+   */
+  const getStatus = async (): Promise<SearchStatus> => {
+    // Codebase status
+    const codebaseFiles = await state.memoryStorage.getAllCodebaseFiles();
+    const codebaseStats = await state.memoryStorage.getCodebaseIndexStats();
+    const codebaseIndexingStatus = state.codebaseIndexer?.getStatus();
+
+    // Knowledge status
+    const knowledgeStatus = state.knowledgeIndexer.getStatus();
+    let knowledgeIndexed = false;
+    let knowledgeDocCount = 0;
+
+    try {
+      const knowledgeIndex = await state.knowledgeIndexer.loadIndex();
+      knowledgeIndexed = true;
+      knowledgeDocCount = knowledgeIndex.totalDocuments;
+    } catch {
+      // Not indexed yet
+    }
+
+    return {
+      codebase: {
+        indexed: codebaseFiles.length > 0,
+        fileCount: codebaseFiles.length,
+        indexedAt: codebaseStats.indexedAt,
+        isIndexing: codebaseIndexingStatus?.isIndexing || false,
+        progress: codebaseIndexingStatus?.progress || 0,
+        currentFile: codebaseIndexingStatus?.currentFile,
+      },
+      knowledge: {
+        indexed: knowledgeIndexed,
+        documentCount: knowledgeDocCount,
+        isIndexing: knowledgeStatus.isIndexing,
+        progress: knowledgeStatus.progress,
+      },
+    };
+  };
+
+  /**
+   * Search codebase - shared by CLI and MCP
+   */
+  const searchCodebase = async (
+    query: string,
+    options: SearchOptions = {}
+  ): Promise<{
+    results: SearchResult[];
+    totalIndexed: number;
+    query: string;
+  }> => {
+    const {
+      limit = 10,
+      include_content = true,
+      file_extensions,
+      path_filter,
+      exclude_paths,
+      min_score = 0.001, // Default: filter out zero-score results
+    } = options;
+
+    // Check if codebase is indexed
+    const allFiles = await state.memoryStorage.getAllCodebaseFiles();
+    if (allFiles.length === 0) {
+      throw new Error('Codebase not indexed yet. Run "sylphx search reindex" first.');
+    }
+
+    // Apply filters
+    let files = allFiles;
+    if (file_extensions?.length) {
+      files = files.filter((file) => file_extensions.some((ext) => file.path.endsWith(ext)));
+    }
+    if (path_filter) {
+      files = files.filter((file) => file.path.includes(path_filter));
+    }
+    if (exclude_paths?.length) {
+      files = files.filter((file) => !exclude_paths.some((exclude) => file.path.includes(exclude)));
+    }
+
+    if (files.length === 0) {
+      return {
+        results: [],
+        totalIndexed: allFiles.length,
+        query,
+      };
+    }
+
+    // Use TF-IDF index from database to avoid rebuilding
+    const { buildSearchIndexFromDB } = await import('./tfidf.js');
+    const index = await buildSearchIndexFromDB(state.memoryStorage, {
+      file_extensions,
+      path_filter,
+      exclude_paths,
+    });
+
+    if (!index) {
+      throw new Error('No searchable content found');
+    }
+
+    // Process query TF-IDF vector using database values
+    const { processQuery } = await import('./tfidf.js');
+    const queryVector = await processQuery(query, index.idf);
+
+    // Calculate query magnitude
+    let queryMagnitude = 0;
+    for (const value of queryVector.values()) {
+      queryMagnitude += value * value;
+    }
+    queryMagnitude = Math.sqrt(queryMagnitude);
+
+    // Calculate similarity manually (don't use searchDocuments to avoid reprocessing query)
+    const searchResults = index.documents.map((doc) => {
+      let dotProduct = 0;
+      const matchedTerms: string[] = [];
+
+      // Calculate dot product
+      for (const [term, queryScore] of queryVector.entries()) {
+        const docScore = doc.terms.get(term) || 0;
+        if (docScore > 0) {
+          dotProduct += queryScore * docScore;
+          matchedTerms.push(term);
+        }
+      }
+
+      // Calculate cosine similarity
+      let similarity = 0;
+      if (queryMagnitude > 0 && doc.magnitude > 0) {
+        similarity = dotProduct / (queryMagnitude * doc.magnitude);
+      }
+
+      // Use pure TF-IDF score without extra boosting
+      // StarCoder2 tokenization is already optimal
+      const finalScore = similarity;
+
+      return {
+        uri: doc.uri,
+        score: finalScore,
+        matchedTerms,
+      };
+    });
+
+    // Convert result format
+    const results: SearchResult[] = [];
+    for (const result of searchResults) {
+      const filename = result.uri?.replace('file://', '') || 'Unknown';
+      let content = '';
+
+      if (include_content && result.matchedTerms.length > 0) {
+        const file = await state.memoryStorage.getCodebaseFile(filename);
+        if (file?.content) {
+          // Find lines containing matched terms (show context)
+          const lines = file.content.split('\n');
+          const matchedLines: string[] = [];
+
+          for (let i = 0; i < lines.length && matchedLines.length < 3; i++) {
+            const line = lines[i].toLowerCase();
+            if (result.matchedTerms.some((term) => line.includes(term.toLowerCase()))) {
+              matchedLines.push(lines[i].substring(0, 100)); // Limit line length
+            }
+          }
+
+          if (matchedLines.length > 0) {
+            content = matchedLines.join('\n');
+          }
+        }
+      }
+
+      results.push({
+        uri: result.uri,
+        score: result.score || 0,
+        title: filename.split('/').pop() || filename,
+        content: include_content && content ? content : undefined,
+      });
+    }
+
+    // Sort by score (descending), filter by min_score, and limit results
+    const filteredResults = results
+      .filter((r) => r.score >= min_score)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    return {
+      results: filteredResults,
+      totalIndexed: allFiles.length,
+      query,
+    };
+  };
+
+  /**
+   * Search knowledge base - shared by CLI and MCP
+   * Hybrid mode: Uses vector search if API key provided, falls back to TF-IDF otherwise
+   */
+  const searchKnowledge = async (
+    query: string,
+    options: SearchOptions = {}
+  ): Promise<{
+    results: SearchResult[];
+    totalIndexed: number;
+    query: string;
+  }> => {
+    const { limit = 10, include_content = true } = options;
+
+    try {
+      const index = await state.knowledgeIndexer.loadIndex();
+
+      // Hybrid mode: Check if vector search is available
+      const vectorStorage = state.knowledgeIndexer.getVectorStorage();
+
+      let searchResults: Array<{ uri: string; score: number }>;
+
+      if (vectorStorage && state.embeddingProvider) {
+        // Has API key → Use vector search
+        try {
+          const queryEmbeddings = await state.embeddingProvider.generateEmbeddings([query]);
+          const queryEmbedding = queryEmbeddings[0];
+
+          const vectorResults = await vectorStorage.search(queryEmbedding, {
+            k: limit,
+          });
+
+          searchResults = vectorResults.map((result) => ({
+            uri: result.doc.id,
+            score: result.similarity,
+          }));
+        } catch (_error) {
+          // Fallback to TF-IDF if vector search fails
+          searchResults = await searchDocuments(query, index, {
+            limit,
+            boostFactors: {
+              exactMatch: 1.5,
+              phraseMatch: 2.0,
+              technicalMatch: 1.8,
+              identifierMatch: 1.3,
+            },
+          });
+        }
+      } else {
+        // No API key → Use TF-IDF search
+        searchResults = await searchDocuments(query, index, {
+          limit,
+          boostFactors: {
+            exactMatch: 1.5,
+            phraseMatch: 2.0,
+            technicalMatch: 1.8,
+            identifierMatch: 1.3,
+          },
+        });
+      }
+
+      const results: SearchResult[] = searchResults.map((result) => ({
+        uri: result.uri,
+        score: result.score || 0,
+        title: result.uri?.split('/').pop() || 'Unknown',
+        content: include_content ? '' : undefined,
+      }));
+
+      return {
+        results,
+        totalIndexed: index.totalDocuments,
+        query,
+      };
+    } catch {
+      throw new Error('Knowledge base not indexed yet');
+    }
+  };
+
+  /**
+   * Format search results for CLI output
+   */
+  const formatResultsForCLI = (
+    results: SearchResult[],
+    query: string,
+    totalIndexed: number
+  ): string => {
+    if (results.length === 0) {
+      return `📭 No results found for "${query}"\n\n**Total indexed files:** ${totalIndexed}`;
+    }
+
+    const summary = `✓ Found ${results.length} result(s) for "${query}":\n\n`;
+    const formattedResults = results
+      .map((result, i) => {
+        let line = `${i + 1}. **${result.title}** (Score: ${result.score.toFixed(3)})`;
+
+        // Display full path or URI
+        if (result.uri.startsWith('file://')) {
+          const filePath = result.uri.replace('file://', '');
+          line += `\n   📁 Path: \`${filePath}\``;
+        } else if (result.uri.startsWith('knowledge://')) {
+          line += `\n   📚 Source: ${result.uri}`;
+        } else {
+          line += `\n   🔗 URI: ${result.uri}`;
+        }
+
+        if (result.content) {
+          line += `\n   \`\`\`\n${result.content}\n\`\`\``;
+        }
+        return line;
+      })
+      .join('\n\n');
+
+    return summary + formattedResults;
+  };
+
+  /**
+   * Format search results for MCP response
+   */
+  const formatResultsForMCP = (
+    results: SearchResult[],
+    query: string,
+    _totalIndexed: number
+  ): {
+    content: Array<{ type: 'text'; text: string }>;
+  } => {
+    const summary = `Found ${results.length} result(s) for "${query}":\n\n`;
+    const formattedResults = results
+      .map((result, i) => {
+        let line = `${i + 1}. **${result.title}** (Score: ${result.score.toFixed(3)})`;
+
+        // Include URI for knowledge_get tool
+        if (result.uri.startsWith('file://')) {
+          const filePath = result.uri.replace('file://', '');
+          line += `\n   📁 Path: \`${filePath}\``;
+        } else if (result.uri.startsWith('knowledge://')) {
+          line += `\n   📚 URI: ${result.uri}`;
+        } else {
+          line += `\n   🔗 URI: ${result.uri}`;
+        }
+
+        if (result.content) {
+          line += `\n\`\`\`\n${result.content}\n\`\`\``;
+        }
+        return line;
+      })
+      .join('\n\n');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: summary + formattedResults,
+        },
+      ],
+    };
+  };
+
+  /**
+   * Get all available knowledge URIs - dynamically generated
+   */
+  const getAvailableKnowledgeURIs = async (): Promise<string[]> => {
+    try {
+      const index = await state.knowledgeIndexer.loadIndex();
+      return index.documents.map((doc) => doc.uri);
+    } catch {
+      return [];
+    }
+  };
+
+  /**
+   * Start codebase file watching
+   * IMPORTANT: Only call when codebase tools are enabled in MCP server
+   * Prevents stale codebase data from misleading users
+   */
+  const startCodebaseWatching = (): void => {
+    if (!state.codebaseIndexer) {
+      state.codebaseIndexer = new CodebaseIndexer();
+    }
+    state.codebaseIndexer.startWatching();
+  };
+
+  /**
+   * Stop codebase file watching
+   * Called when codebase tools are disabled or MCP server shuts down
+   */
+  const stopCodebaseWatching = (): void => {
+    if (state.codebaseIndexer) {
+      state.codebaseIndexer.stopWatching();
+    }
+  };
+
+  // Return service interface
+  return {
+    initialize,
+    getStatus,
+    searchCodebase,
+    searchKnowledge,
+    formatResultsForCLI,
+    formatResultsForMCP,
+    getAvailableKnowledgeURIs,
+    startCodebaseWatching,
+    stopCodebaseWatching,
+  };
+};
+
+// ============================================================================
+// FUNCTIONAL SEARCH PIPELINES (Pure Functions)
+// ============================================================================
+
+/**
+ * Pure function: Apply file extension filter
+ */
+const filterByExtensions = (extensions?: string[]) =>
+  filter((file: any) => !extensions?.length || extensions.some((ext) => file.path.endsWith(ext)));
+
+/**
+ * Pure function: Apply path filter
+ */
+const filterByPath = (pathFilter?: string) =>
+  filter((file: any) => !pathFilter || file.path.includes(pathFilter));
+
+/**
+ * Pure function: Apply exclude paths filter
+ */
+const filterByExcludePaths = (excludePaths?: string[]) =>
+  filter(
+    (file: any) =>
+      !excludePaths?.length || !excludePaths.some((exclude) => file.path.includes(exclude))
+  );
+
+/**
+ * Pure function: Calculate cosine similarity between query and document
+ */
+const calculateSimilarity =
+  (queryVector: Map<string, number>, queryMagnitude: number) => (doc: any) => {
+    let dotProduct = 0;
+    const matchedTerms: string[] = [];
+
+    // Calculate dot product
+    for (const [term, queryScore] of queryVector.entries()) {
+      const docScore = doc.terms.get(term) || 0;
+      if (docScore > 0) {
+        dotProduct += queryScore * docScore;
+        matchedTerms.push(term);
+      }
+    }
+
+    // Calculate cosine similarity
+    let similarity = 0;
+    if (queryMagnitude > 0 && doc.magnitude > 0) {
+      similarity = dotProduct / (queryMagnitude * doc.magnitude);
+    }
+
+    return {
+      uri: doc.uri,
+      score: similarity,
+      matchedTerms,
+    };
+  };
+
+/**
+ * Pure function: Extract matched lines from content
+ */
+const extractMatchedLines = (
+  content: string,
+  matchedTerms: string[],
+  maxLines = 3,
+  maxLineLength = 100
+): string => {
+  const lines = content.split('\n');
+  const matchedLines: string[] = [];
+
+  for (let i = 0; i < lines.length && matchedLines.length < maxLines; i++) {
+    const line = lines[i].toLowerCase();
+    if (matchedTerms.some((term) => line.includes(term.toLowerCase()))) {
+      matchedLines.push(lines[i].substring(0, maxLineLength));
+    }
+  }
+
+  return matchedLines.join('\n');
+};
+
+/**
+ * Pure function: Convert search result to SearchResult format
+ */
+const toSearchResult =
+  (includeContent: boolean) =>
+  (result: {
+    uri: string;
+    score: number;
+    matchedTerms: string[];
+    content?: string;
+  }): SearchResult => {
+    const filename = result.uri?.replace('file://', '') || 'Unknown';
+    return {
+      uri: result.uri,
+      score: result.score || 0,
+      title: filename.split('/').pop() || filename,
+      content: includeContent && result.content ? result.content : undefined,
+    };
+  };
+
+/**
+ * Pure function: Filter by minimum score
+ */
+const filterByMinScore = (minScore: number) =>
+  filter((result: SearchResult) => result.score >= minScore);
+
+/**
+ * Functional searchCodebase implementation
+ * Uses pure functions and pipelines instead of imperative code
+ *
+ * @example
+ * const results = await searchCodebaseFunctional(storage, 'authentication', { limit: 5 });
+ */
+export async function searchCodebaseFunctional(
+  storage: SeparatedMemoryStorage,
+  query: string,
+  options: SearchOptions = {}
+): Promise<{
+  results: SearchResult[];
+  totalIndexed: number;
+  query: string;
+}> {
+  const {
+    limit = 10,
+    include_content = true,
+    file_extensions,
+    path_filter,
+    exclude_paths,
+    min_score = 0.001,
+  } = options;
+
+  // Get all files
+  const allFiles = await storage.getAllCodebaseFiles();
+  if (allFiles.length === 0) {
+    throw new Error('Codebase not indexed yet. Run "sylphx search reindex" first.');
+  }
+
+  // Apply filters using functional pipeline
+  const files = pipe(
+    allFiles,
+    filterByExtensions(file_extensions),
+    filterByPath(path_filter),
+    filterByExcludePaths(exclude_paths)
+  );
+
+  if (files.length === 0) {
+    return {
+      results: [],
+      totalIndexed: allFiles.length,
+      query,
+    };
+  }
+
+  // Build index
+  const { buildSearchIndexFromDB } = await import('./tfidf.js');
+  const index = await buildSearchIndexFromDB(storage, {
+    file_extensions,
+    path_filter,
+    exclude_paths,
+  });
+
+  if (!index) {
+    throw new Error('No searchable content found');
+  }
+
+  // Process query
+  const { processQuery } = await import('./tfidf.js');
+  const queryVector = await processQuery(query, index.idf);
+
+  // Calculate query magnitude
+  const queryMagnitude = Math.sqrt(
+    Array.from(queryVector.values()).reduce((sum, val) => sum + val * val, 0)
+  );
+
+  // Calculate similarities using functional pipeline
+  const searchResults = pipe(
+    index.documents,
+    map(calculateSimilarity(queryVector, queryMagnitude))
+  );
+
+  // Extract content for results with matched terms (async operation)
+  const resultsWithContent = await Promise.all(
+    searchResults.map(async (result) => {
+      if (include_content && result.matchedTerms.length > 0) {
+        const filename = result.uri?.replace('file://', '') || '';
+        const file = await storage.getCodebaseFile(filename);
+        const content = file?.content ? extractMatchedLines(file.content, result.matchedTerms) : '';
+        return { ...result, content };
+      }
+      return { ...result, content: '' };
+    })
+  );
+
+  // Final pipeline: convert format, filter, sort, limit
+  const filteredResults = pipe(
+    resultsWithContent,
+    map(toSearchResult(include_content)),
+    filterByMinScore(min_score),
+    (results) => results.sort((a, b) => b.score - a.score),
+    take(limit)
+  );
+
+  return {
+    results: filteredResults,
+    totalIndexed: allFiles.length,
+    query,
+  };
+}
+
+/**
+ * Functional searchKnowledge implementation
+ * Hybrid mode: Uses vector search if available, falls back to TF-IDF
+ *
+ * @example
+ * const results = await searchKnowledgeFunctional(indexer, embeddingProvider, 'react hooks', { limit: 10 });
+ */
+export async function searchKnowledgeFunctional(
+  knowledgeIndexer: ReturnType<typeof getKnowledgeIndexer>,
+  embeddingProvider: EmbeddingProvider | undefined,
+  query: string,
+  options: SearchOptions = {}
+): Promise<{
+  results: SearchResult[];
+  totalIndexed: number;
+  query: string;
+}> {
+  const { limit = 10, include_content = true } = options;
+
+  try {
+    const index = await knowledgeIndexer.loadIndex();
+
+    // Hybrid mode: Check if vector search is available
+    const vectorStorage = knowledgeIndexer.getVectorStorage();
+
+    let searchResults: Array<{ uri: string; score: number }>;
+
+    if (vectorStorage && embeddingProvider) {
+      // Has API key → Use vector search
+      try {
+        const queryEmbeddings = await embeddingProvider.generateEmbeddings([query]);
+        const queryEmbedding = queryEmbeddings[0];
+
+        const vectorResults = await vectorStorage.search(queryEmbedding, {
+          k: limit,
+        });
+
+        searchResults = vectorResults.map((result) => ({
+          uri: result.doc.id,
+          score: result.similarity,
+        }));
+      } catch {
+        // Fallback to TF-IDF if vector search fails
+        searchResults = await searchDocuments(query, index, {
+          limit,
+          boostFactors: {
+            exactMatch: 1.5,
+            phraseMatch: 2.0,
+            technicalMatch: 1.8,
+            identifierMatch: 1.3,
+          },
+        });
+      }
+    } else {
+      // No API key → Use TF-IDF search
+      searchResults = await searchDocuments(query, index, {
+        limit,
+        boostFactors: {
+          exactMatch: 1.5,
+          phraseMatch: 2.0,
+          technicalMatch: 1.8,
+          identifierMatch: 1.3,
+        },
+      });
+    }
+
+    // Functional pipeline: map to SearchResult format
+    const results = pipe(
+      searchResults,
+      map((result: any) => ({
+        uri: result.uri,
+        score: result.score || 0,
+        title: result.uri?.split('/').pop() || 'Unknown',
+        content: include_content ? '' : undefined,
+      }))
+    );
+
+    return {
+      results,
+      totalIndexed: index.totalDocuments,
+      query,
+    };
+  } catch {
+    throw new Error('Knowledge base not indexed yet');
+  }
+}
+
+// ============================================================================
+// FACTORY PATTERN & DEPENDENCY INJECTION
+// ============================================================================
+
+/**
+ * Create search service with custom dependencies
+ * Useful for testing and custom configurations
+ *
+ * @example
+ * // Custom service for testing
+ * const testService = createSearchService({
+ *   memoryStorage: mockStorage,
+ *   knowledgeIndexer: mockKnowledgeIndexer,
+ * });
+ *
+ * // Custom service with specific configuration
+ * const customService = createSearchService({
+ *   embeddingProvider: myEmbeddingProvider,
+ * });
+ */
+export const createSearchService = (
+  dependencies?: SearchServiceDependencies
+): UnifiedSearchService => {
+  return createUnifiedSearchService(dependencies);
+};
+
+/**
+ * Lazy search service instance (singleton)
+ * Used by CLI and MCP for standard operation
+ *
+ * IMPORTANT: This is NOT created at module load time to avoid starting
+ * file watchers during init command. Use getSearchService() to access it.
+ */
+let _searchServiceInstance: UnifiedSearchService | null = null;
+
+/**
+ * Get the search service singleton (lazy initialization)
+ * This is the preferred way to access the search service.
+ */
+export function getSearchService(): UnifiedSearchService {
+  if (!_searchServiceInstance) {
+    _searchServiceInstance = createUnifiedSearchService();
+  }
+  return _searchServiceInstance;
+}
+
+/**
+ * Create test search service with mock dependencies
+ * Convenience function for testing
+ *
+ * @example
+ * const testService = createTestSearchService({
+ *   memoryStorage: mockStorage,
+ * });
+ */
+export const createTestSearchService = (
+  mockDependencies: Partial<SearchServiceDependencies> = {}
+): UnifiedSearchService => {
+  return createUnifiedSearchService({
+    memoryStorage: mockDependencies.memoryStorage,
+    knowledgeIndexer: mockDependencies.knowledgeIndexer,
+    codebaseIndexer: mockDependencies.codebaseIndexer,
+    embeddingProvider: mockDependencies.embeddingProvider,
+  });
+};