@ngao/search 0.1.0 → 0.1.2

package/src/backend/services/session-manager.ts

@@ -0,0 +1,214 @@
+/**
+ * Session Manager for NGAO Search
+ * Manages user sessions and tracks search history
+ */
+
+import { v4 as uuid } from 'uuid';
+
+/**
+ * Represents a user session with search history
+ */
+export interface Session {
+  /** Unique session identifier */
+  sessionId: string;
+  /** Unix timestamp when session was created */
+  startedAt: number;
+  /** Unix timestamp of last activity */
+  lastActivity: number;
+  /** Search history entries for this session */
+  searchHistory: SearchHistoryEntry[];
+}
+
+/**
+ * Represents a single search query in history
+ */
+export interface SearchHistoryEntry {
+  /** Unique identifier for this history entry */
+  id: string;
+  /** Original search query string */
+  query: string;
+  /** Unix timestamp when search was performed */
+  timestamp: number;
+  /** Number of results returned */
+  resultCount: number;
+  /** Execution time in milliseconds */
+  executionTimeMs: number;
+  /** Optional filters applied to search */
+  filters?: Record<string, unknown>;
+  /** Item types queried */
+  itemTypesQueried?: string[];
+  /** File types queried */
+  fileTypesQueried?: string[];
+  /** Minimum relevance threshold applied */
+  minRelevanceApplied?: number;
+  /** Brief explanation of why results matched */
+  explanation?: string;
+}
+
+/**
+ * Manages user sessions and search history
+ * Provides session lifecycle management and history tracking
+ */
+export class SessionManager {
+  /** In-memory store of active sessions */
+  private _sessions: Map<string, Session> = new Map();
+
+  /** Cleanup interval timer */
+  private _cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Session timeout in milliseconds (30 minutes) */
+  private readonly SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+
+  /** Cleanup interval in milliseconds (1 minute) */
+  private readonly CLEANUP_INTERVAL_MS = 60 * 1000;
+
+  /** Maximum search history size per session */
+  private readonly MAX_HISTORY_SIZE = 100;
+
+  /**
+   * Initialize SessionManager and start cleanup timer
+   */
+  public constructor() {
+    this._startCleanupTimer();
+  }
+
+  /**
+   * Create a new session
+   * @returns New session ID
+   */
+  public createSession(): string {
+    const sessionId = uuid();
+    const now = Date.now();
+
+    this._sessions.set(sessionId, {
+      sessionId,
+      startedAt: now,
+      lastActivity: now,
+      searchHistory: [],
+    });
+
+    return sessionId;
+  }
+
+  /**
+   * Retrieve an existing session
+   * @param sessionId - Session ID to retrieve
+   * @returns Session object or null if not found
+   */
+  public getSession(sessionId: string): Session | null {
+    return this._sessions.get(sessionId) || null;
+  }
+
+  /**
+   * Add a search entry to session history
+   * @param sessionId - Session ID
+   * @param entry - Search history entry to add
+   */
+  public addSearchToHistory(sessionId: string, entry: SearchHistoryEntry): void {
+    const session = this._sessions.get(sessionId);
+    if (!session) {
+      return; // Silently fail if session not found
+    }
+
+    // Add to history
+    session.searchHistory.push(entry);
+
+    // Enforce max history size (keep most recent)
+    if (session.searchHistory.length > this.MAX_HISTORY_SIZE) {
+      session.searchHistory = session.searchHistory.slice(-this.MAX_HISTORY_SIZE);
+    }
+
+    // Update last activity
+    session.lastActivity = Date.now();
+  }
+
+  /**
+   * Retrieve search history for a session
+   * @param sessionId - Session ID
+   * @returns Array of search history entries or null if session not found
+   */
+  public getSearchHistory(sessionId: string): SearchHistoryEntry[] | null {
+    const session = this._sessions.get(sessionId);
+    if (!session) {
+      return null;
+    }
+
+    // Update last activity
+    session.lastActivity = Date.now();
+
+    return session.searchHistory;
+  }
+
+  /**
+   * End a session and remove it
+   * @param sessionId - Session ID to end
+   */
+  public endSession(sessionId: string): void {
+    this._sessions.delete(sessionId);
+  }
+
+  /**
+   * Get all active sessions
+   * @returns Array of all active session IDs
+   */
+  public getActiveSessions(): string[] {
+    return Array.from(this._sessions.keys());
+  }
+
+  /**
+   * Cleanup expired sessions
+   * @private
+   */
+  private _cleanupExpiredSessions(): void {
+    const now = Date.now();
+    const expiredSessionIds: string[] = [];
+
+    // Find expired sessions
+    for (const [sessionId, session] of this._sessions.entries()) {
+      if (now - session.lastActivity > this.SESSION_TIMEOUT_MS) {
+        expiredSessionIds.push(sessionId);
+      }
+    }
+
+    // Remove expired sessions
+    for (const sessionId of expiredSessionIds) {
+      this._sessions.delete(sessionId);
+    }
+  }
+
+  /**
+   * Start the cleanup timer
+   * @private
+   */
+  private _startCleanupTimer(): void {
+    this._cleanupTimer = setInterval(() => {
+      this._cleanupExpiredSessions();
+    }, this.CLEANUP_INTERVAL_MS);
+
+    // Unref timer so it doesn't prevent process exit
+    if (this._cleanupTimer.unref) {
+      this._cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Stop the cleanup timer
+   * @private
+   */
+  private _stopCleanupTimer(): void {
+    if (this._cleanupTimer) {
+      clearInterval(this._cleanupTimer);
+      this._cleanupTimer = null;
+    }
+  }
+
+  /**
+   * Destroy the session manager (cleanup resources)
+   */
+  public destroy(): void {
+    this._stopCleanupTimer();
+    this._sessions.clear();
+  }
+}
+
+

package/src/cli/setup.ts

@@ -0,0 +1,122 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { execSync } from 'child_process';
+import { v4 as uuidv4 } from 'uuid';
+import * as os from 'os';
+import { NgaoSearchService } from '../backend/services/ngao-search-service';
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function question(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      resolve(answer);
+    });
+  });
+}
+
+export async function setupMCP(): Promise<{ projectDir: string }> {
+  console.log('\n🔧 NGAO Search - MCP Setup for Claude Code\n');
+
+  // Ask for project directory
+  const projectDir = await question('📁 Enter your project directory path (or press Enter for current): ');
+  const resolvedProjectDir = projectDir.trim() || process.cwd();
+
+  // Create .ngao-search config in project
+  const projectConfigPath = path.join(resolvedProjectDir, '.ngao-search.json');
+  if (!fs.existsSync(projectConfigPath)) {
+    // Generate UUID for this project to isolate its database
+    const projectUUID = uuidv4();
+    const projectConfig = {
+      projectId: projectUUID,
+      includePaths: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.py', '**/*.md'],
+      excludePaths: ['node_modules/**', 'dist/**', '.git/**'],
+    };
+    fs.writeFileSync(projectConfigPath, JSON.stringify(projectConfig, null, 2));
+    console.log(`✅ Project config created: ${projectConfigPath}`);
+    console.log(`📋 Project ID: ${projectUUID}`);
+  }
+
+  // Create .mcp-config.json in project for reference
+  const mcpConfigPath = path.join(resolvedProjectDir, '.mcp-config.json');
+  const mcpConfig = {
+    mcpServers: {
+      'ngao-search': {
+        command: 'npx',
+        args: ['ngao-search'],
+        env: {
+          NGAO_SEARCH_PROJECT: resolvedProjectDir,
+          MCP_TRANSPORT: 'stdio',
+        },
+      },
+    },
+  };
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+  console.log(`✅ MCP config created: ${mcpConfigPath}`);
+
+  // Register with Claude Code CLI using `claude mcp add`
+  try {
+    console.log('\n📡 Registering with Claude Code CLI...');
+    execSync(
+      `cd "${resolvedProjectDir}" && claude mcp add -e NGAO_SEARCH_PROJECT="${resolvedProjectDir}" -e MCP_TRANSPORT=stdio -- ngao-search npx ngao-search`,
+      { stdio: 'pipe' }
+    );
+    console.log('✅ MCP server registered with Claude Code CLI');
+  } catch (error) {
+    console.log('⚠️  Could not auto-register with Claude Code CLI.');
+    console.log('   Please run this command manually in your project directory:');
+    console.log(`\n   cd "${resolvedProjectDir}"`);
+    console.log('   claude mcp add -e NGAO_SEARCH_PROJECT="' + resolvedProjectDir + '" -e MCP_TRANSPORT=stdio -- ngao-search npx ngao-search\n');
+  }
+
+  // Initialize database (embedding model will lazy-load on first search)
+  console.log('\n⚙️  Initializing database...');
+  let searchService: NgaoSearchService | null = null;
+  try {
+    searchService = new NgaoSearchService(resolvedProjectDir);
+    await searchService.ensureInitialized();
+    console.log('✅ Database initialized');
+    console.log('   Embedding model will load on first search');
+  } catch (error) {
+    console.warn('⚠️  Warning: Could not initialize database');
+    console.warn(`   Error: ${String(error)}`);
+    console.log('   Database will be initialized on first use instead.\n');
+  }
+
+  // Auto-index the project directory
+  if (searchService) {
+    console.log('\n📑 Auto-indexing project directory...');
+    try {
+      const indexResult = await searchService.autoIndexProjectDirectory(resolvedProjectDir);
+      if (indexResult.success && indexResult.stats) {
+        console.log('✅ Auto-indexing completed');
+        console.log(`   📊 Indexed ${indexResult.stats.totalFiles} files with ${indexResult.stats.totalBlocks} code blocks`);
+      } else {
+        console.warn(`⚠️  Auto-indexing encountered issues: ${indexResult.error || 'Unknown error'}`);
+        console.log('   You can manually index later using the search tools\n');
+      }
+    } catch (error) {
+      console.warn('⚠️  Warning: Could not auto-index project directory');
+      console.warn(`   Error: ${String(error)}`);
+      console.log('   You can manually index later using the search tools\n');
+    }
+  }
+
+  // Show setup instructions
+  console.log('\n📝 Setup Complete!\n');
+  console.log('✨ NGAO Search is now integrated with Claude Code');
+  console.log('\nℹ️  Configuration Details:');
+  console.log('📍 Project directory: ' + resolvedProjectDir);
+  console.log('🔌 Server port: Automatically assigned');
+  console.log('📌 Project config: ' + projectConfigPath);
+  console.log('📌 MCP config: ' + mcpConfigPath + '\n');
+  console.log('🚀 You can now use NGAO Search in Claude Code!\n');
+
+  rl.close();
+  return { projectDir: resolvedProjectDir };
+}
+

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * NGAO Search - Main Entry Point
+ * Re-exports from backend for backward compatibility
+ */
+
+export * from './backend';

package/src/main.ts

@@ -0,0 +1,225 @@
+/**
+ * Unified Entry Point for NGAO Search
+ * Supports multiple transport modes: stdio (MCP) or http (REST)
+ *
+ * Transport selection via environment variable:
+ * - MCP_TRANSPORT=stdio  - Start MCP stdio server only (for Claude Desktop)
+ * - MCP_TRANSPORT=http   - Start REST HTTP server only (default)
+ * - --setup             - Run interactive MCP setup for Claude
+ * - --help, -h          - Show help documentation with tool descriptions
+ *
+ * All transports share the same NgaoSearchService instance
+ */
+
+import { NgaoSearchService } from './backend/services/ngao-search-service';
+import { McpTransport } from './server/transports/mcp-transport';
+import { RestTransport } from './server/transports/rest-transport';
+import { createLogger } from './server/logger';
+
+// Check for --setup flag for interactive setup
+const args = process.argv.slice(2);
+const setupMode = args.includes('--setup') || process.env.NGAO_SETUP;
+const helpMode = args.includes('--help') || args.includes('-h') || process.env.NGAO_HELP;
+
+// Show help if requested (check early before anything else)
+if (helpMode) {
+  console.log(`
+╔════════════════════════════════════════════════════════════════════════════╗
+║              NGAO Search - Model Context Protocol Server                    ║
+║              Local Code/Document Search with LLM-Friendly Output            ║
+╚════════════════════════════════════════════════════════════════════════════╝
+
+📖 USAGE
+  ngao-search [COMMAND] [OPTIONS]
+  OR with npx:
+  npx ngao-search -- --help
+  OR with environment variable:
+  NGAO_HELP=true npx ngao-search
+
+🔧 SETUP
+  ngao-search --setup
+  OR: npx ngao-search -- --setup
+  OR: NGAO_SETUP=true npx ngao-search
+    Interactively configure NGAO Search for a project.
+    Creates .ngao-search.json with a unique projectId and database isolation.
+
+🚀 START SERVER
+  Default: Start HTTP REST API on a random available port
+  MCP_TRANSPORT=stdio ngao-search
+  OR: MCP_TRANSPORT=stdio npx ngao-search
+    Start MCP stdio server for Claude Code/Desktop integration
+
+💡 AVAILABLE TOOLS (for LLMs)
+
+1. search [REQUIRED]
+   Search through indexed code and documentation
+   Parameters:
+     - query: string (required) - Search query
+     - maxResults: number (optional) - Max results to return (default: 100)
+     - sessionId: string (optional) - Session ID for history tracking
+
+2. index [REQUIRED]
+   Index a directory for searching
+   Parameters:
+     - dirPath: string (required) - Directory path to index
+
+3. list_indexed_dirs
+   List all indexed directories
+   No parameters required
+
+4. get_stats
+   Get indexing statistics
+   No parameters required
+
+5. get_index_info
+   Get detailed index information with file breakdown
+   No parameters required
+
+6. get_file_statistics
+   Get per-file index statistics
+   Parameters:
+     - filePath: string (optional) - Specific file path
+
+7. get_search_history
+   Get search history for a session
+   Parameters:
+     - sessionId: string (required) - Session ID
+
+8. start_reindex
+   Start a reindex operation
+   Parameters:
+     - dirPath: string (required) - Directory to reindex
+     - mode: string (optional) - 'incremental' or 'full' (default: 'incremental')
+
+9. get_reindex_status
+   Get reindex operation status
+   Parameters:
+     - reindexId: string (required) - Reindex operation ID
+
+🔑 KEY FEATURES
+
+• 📁 Multi-Language Support
+  Supports TypeScript, JavaScript, Python, Markdown, YAML, JSON, and more
+
+• 🧠 Semantic Search
+  Uses vector embeddings for intelligent code/doc search
+
+• 🗂️  Project Isolation
+  Each project gets a unique database stored in ~/.ngao/ directory
+  
+• 💾 Persistent Storage
+  Uses LanceDB for reliable vector storage
+
+• 📊 Session Tracking
+  Track search history within sessions for context awareness
+
+• 🔄 Reindexing
+  Incremental or full reindex support for keeping index up-to-date
+
+⚙️  CONFIGURATION
+
+Project config stored in .ngao-search.json:
+  {
+    "projectId": "unique-uuid-for-database-isolation",
+    "includePaths": ["**/*.ts", "**/*.js", "**/*.py", "**/*.md"],
+    "excludePaths": ["node_modules/**", "dist/**", ".git/**"]
+  }
+
+Database Location: ~/.ngao/{projectId}.lancedb
+Metadata Location: ~/.ngao/{projectId}.metadata.json
+
+🎯 WORKFLOW FOR LLMs
+
+1. Call index() with your project directory
+2. Call search() to find relevant code/docs
+3. Use get_stats() to check indexing progress
+4. Use get_index_info() to understand code structure
+5. Call start_reindex() when code changes
+6. Track session history with sessionId for context
+
+📚 MORE INFO
+  github.com/ngao-team/ngao-search
+  
+`);
+  process.exit(0);
+}
+
+// When setup completes, auto-start in MCP stdio mode for Claude
+if (setupMode) {
+  process.env.MCP_TRANSPORT = 'stdio';
+}
+
+const transport = (process.env.MCP_TRANSPORT || 'http').toLowerCase();
+
+/**
+ * Main async function
+ */
+async function main(): Promise<void> {
+  // Run setup first if requested, then continue to start server
+  if (setupMode) {
+    try {
+      const { setupMCP } = await import('./cli/setup');
+      const { projectDir } = await setupMCP();
+      // Set environment vars for server startup
+      process.env.NGAO_SEARCH_PROJECT = projectDir;
+      console.log('\n🚀 Starting NGAO Search MCP server...\n');
+      // Continue to server startup below
+    } catch (error) {
+      console.error('Setup failed:', error);
+      process.exit(1);
+    }
+  }
+
+  try {
+    // Create shared service instance
+    const service = new NgaoSearchService();
+
+    // Eagerly initialize database on startup
+    // (embedding model will lazy-load on first search to avoid network dependency)
+    try {
+      await service.ensureInitialized();
+    } catch (error) {
+      // Log database initialization errors
+      console.warn('Warning: Could not initialize database:', String(error));
+    }
+
+    switch (transport) {
+      case 'stdio': {
+        const logger = createLogger('stdio');
+        logger.info('Transport: MCP stdio (Claude Desktop)');
+        logger.info('Initializing NgaoSearchService');
+
+        const mcpTransport = new McpTransport(service, logger);
+        await mcpTransport.start();
+
+        logger.info('NGAO Search server started successfully');
+        break;
+      }
+
+      case 'http': {
+        const logger = createLogger('http');
+        logger.info('Transport: HTTP REST API');
+        logger.info('Initializing NgaoSearchService');
+
+        const restTransport = new RestTransport(service, logger);
+        restTransport.start(0); // 0 = randomly assigned available port
+
+        logger.info('NGAO Search server started successfully');
+        break;
+      }
+
+      default:
+        console.error(`❌ Unknown transport: ${transport}`);
+        console.error('   Valid options: stdio, http');
+        console.error('   Default: http');
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error('❌ Failed to start NGAO Search server:');
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+// Start the server
+main();