solver-sdk 5.4.0 → 5.6.0

package/README.md

@@ -12,34 +12,40 @@ npm install solver-sdk
 
 ## 🚀 Быстрый старт
 
-```javascript
+```typescript
 import { CodeSolverSDK } from 'solver-sdk';
 
 const sdk = new CodeSolverSDK({
   baseURL: 'http://localhost:3000',
   apiKey: 'your-api-key',
-  webSocket: { enabled: true } // Включить WebSocket для real-time уведомлений
+  webSocket: { enabled: true }
 });
 
-// Подключение к WebSocket
-await sdk.connectWebSocket();
-
-// Создание проекта
-const project = await sdk.projects.createProject('My Project', '/path/to/project');
-
-// Запуск индексации с real-time статусом
-const indexResult = await sdk.indexing.indexProject('/path', 'My Project');
-
-// Подписка на real-time уведомления
-sdk.projectSync.on('sync-status-update', (status) => {
-  console.log(`Индексация: ${status.progress}%`);
-});
-
-// Поиск по коду
-const results = await sdk.search.searchCode(project.id, {
-  query: 'function authenticate',
-  limit: 10
-});
+// 🔄 Cursor-like workflow для VS Code расширения
+async function openProject(projectPath: string) {
+  // 1. Создать/найти проект
+  const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
+  
+  // 2. Проверить прерванные сессии
+  const recovery = await sdk.projects.getRecoveryStatus(project.id);
+  if (recovery.hasInterruptedSession) {
+    // Показать диалог: "Continue indexing (67%)" или "Start fresh"
+    const choice = await showRecoveryDialog(recovery.recoveryInfo);
+    if (choice === 'continue') {
+      await sdk.projects.resumeSync(project.id);
+    } else {
+      await sdk.projects.cancelRecovery(project.id);
+    }
+  }
+  
+  // 3. Smart Sync - проверить нужна ли синхронизация
+  const hash = await computeMerkleRootHash(projectPath);
+  const state = await sdk.projects.getProjectState(project.id, hash);
+  
+  if (state.syncRequired) {
+    await sdk.projects.initializeDeltaSync(project.id, hash);
+  }
+}
 ```
 
 ## 📖 API Reference
@@ -75,7 +81,7 @@ interface CodeSolverSDKOptions {
 
 ### 📁 Projects API (`sdk.projects`)
 
-#### Управление проектами
+#### 🏗️ Управление проектами
 
 ```typescript
 // Создание проекта
@@ -90,86 +96,54 @@ getProject(projectId: string): Promise<Project | null>
 
 // Поиск или создание проекта
 findOrCreateProject(projectPath: string, projectName: string, description?: string): Promise<Project>
-
-// Получение статуса индексации проекта
-getIndexingStatus(projectId: string): Promise<any>
-```
-
-#### Примеры использования
-
-```javascript
-// Создание нового проекта
-const project = await sdk.projects.createProject(
-  'My Web App',
-  '/Users/dev/my-web-app',
-  { description: 'React приложение' }
-);
-
-// Получение всех проектов пользователя
-const projects = await sdk.projects.getAllProjects();
-console.log(`У вас ${projects.length} проектов`);
-
-// Поиск существующего или создание нового
-const project = await sdk.projects.findOrCreateProject(
-  '/path/to/project',
-  'My Project',
-  'Описание проекта'
-);
 ```
 
-### 🚀 Indexing API (`sdk.indexing`)
-
-#### Управление индексацией
+#### 📊 Управление состоянием и индексацией
 
 ```typescript
-// Создание проекта и запуск индексации
-indexProject(projectPath: string, projectName: string, description?: string): Promise<IndexProjectResult>
-
-// Получение статуса индексации
-getStatus(projectId: string): Promise<IndexingStatus>
-
-// ❌ ОТКЛЮЧЕН: waitForCompletion() - используйте WebSocket!
-
-// Отмена индексации
-cancelIndexing(projectId: string): Promise<void>
+// Получение статуса индексации проекта
+getIndexingStatus(projectId: string): Promise<any>
 
-// Перезапуск индексации
-restartIndexing(projectId: string): Promise<IndexingStatus>
+// 🔍 Проверка состояния проекта (новое в v5.3.2+)
+getProjectState(projectId: string, clientRootHash?: string): Promise<ProjectState>
+
+// 🔄 Проверка прерванных сессий (новое в v5.5.0+)
+getRecoveryStatus(projectId: string): Promise<{
+  hasInterruptedSession: boolean;
+  recoveryInfo?: RecoveryInfo;
+}>
+
+// 🔄 Возобновление прерванной синхронизации (новое в v5.5.0+)
+resumeSync(projectId: string, options?: ResumeOptions): Promise<{
+  success: boolean;
+  message: string;
+  sessionId?: string;
+  continueFromBatch?: number;
+  resumeEndpoint?: string;
+}>
+
+// 🗑️ Отмена прерванной сессии (новое в v5.5.0+)
+cancelRecovery(projectId: string): Promise<{
+  success: boolean;
+  message: string;
+}>
 ```
 
-#### Типы данных
+#### 🧹 Управление данными проекта
 
 ```typescript
-interface IndexingStatus {
-  status: string;           // 'pending' | 'processing' | 'completed' | 'failed'
-  progress: number;         // Прогресс 0-100
-  totalFiles?: number;      // Общее количество файлов
-  processedFiles?: number;  // Обработано файлов
-  currentFile?: string;     // Текущий обрабатываемый файл
-  error?: string;          // Сообщение об ошибке
-  updatedAt?: string;      // Время последнего обновления
-}
+// 🧹 Очистка удаленных файлов (новое в v5.4.0+)
+cleanupDeletedFiles(projectId: string, activeFiles: ActiveFile[]): Promise<FileCleanupResult>
+
+// 🔍 Получение mapping обфусцированных путей (новое в v5.4.0+)
+getFilePathMapping(projectId: string): Promise<{
+  success: boolean;
+  files: FilePathMapping[];
+}>
 ```
 
-#### Примеры использования
 
-```javascript
-// Запуск индексации
-const result = await sdk.indexing.indexProject(
-  '/Users/dev/my-project',
-  'My Project'
-);
-console.log('Project ID:', result.projectId);
-
-// Получение статуса (единичный запрос)
-const status = await sdk.indexing.getStatus(result.projectId);
-console.log(`Прогресс: ${status.progress}%`);
-
-// ⚠️ ВАЖНО: Для real-time статуса используйте WebSocket!
-sdk.projectSync.on('sync-status-update', (status) => {
-  console.log(`Статус обновлен: ${status.status}, прогресс: ${status.progress}%`);
-});
-```
+
 
 ### 🔍 Search API (`sdk.search`)
 
@@ -310,6 +284,164 @@ sdk.projectSync.on('error', (error) => {
 sdk.disconnectWebSocket();
 ```
 
+---
+
+## 🎯 **ПОЛНОЕ РУКОВОДСТВО ПО УПРАВЛЕНИЮ ИНДЕКСАЦИЕЙ**
+
+### 🔄 **Cursor-like Workflow - Рекомендуемый подход**
+
+```typescript
+import { CodeSolverSDK } from 'solver-sdk';
+
+/**
+ * 🎯 ОСНОВНОЙ WORKFLOW - используйте этот паттерн в вашем VS Code расширении
+ */
+async function handleProjectIndexing(projectPath: string) {
+  const sdk = new CodeSolverSDK({ 
+    baseURL: 'http://localhost:3000',
+    apiKey: 'your-api-key' 
+  });
+
+  // 1. 🔍 Получить или создать проект
+  const project = await sdk.projects.findOrCreateProject(
+    projectPath, 
+    path.basename(projectPath)
+  );
+  const projectId = project.id;
+
+  // 2. 🔄 КРИТИЧЕСКИ ВАЖНО: Проверить прерванные сессии
+  const recoveryStatus = await sdk.projects.getRecoveryStatus(projectId);
+
+  if (recoveryStatus.hasInterruptedSession) {
+    // 🎨 Cursor-like UX: Показать диалог восстановления
+    const info = recoveryStatus.recoveryInfo!;
+    const choice = await showUserChoice({
+      title: 'Indexing was interrupted',
+      message: `Indexing was interrupted at ${info.progress.percentage}%. Continue from where you left off?`,
+      buttons: [
+        { text: '🔄 Continue Indexing', value: 'continue' },
+        { text: '🆕 Start Fresh', value: 'fresh' }
+      ]
+    });
+
+    if (choice === 'continue') {
+      return await continueInterruptedIndexing(projectId);
+    } else {
+      return await startFreshIndexing(projectId);
+    }
+  }
+
+  // 3. 🔍 Проверить нужна ли синхронизация (Smart Sync)
+  const clientHash = await computeMerkleRootHash(projectPath);
+  const state = await sdk.projects.getProjectState(projectId, clientHash);
+
+  if (!state.syncRequired) {
+    console.log('✅ Проект актуален, синхронизация не нужна');
+    return { success: true, message: 'Project is up to date' };
+  }
+
+  // 4. 🚀 Начать новую синхронизацию
+  return await startFreshIndexing(projectId, clientHash);
+}
+
+/**
+ * 🔄 Продолжение прерванной индексации
+ */
+async function continueInterruptedIndexing(projectId: string) {
+  const resumed = await sdk.projects.resumeSync(projectId, {
+    skipDuplicates: true,
+    continueFromLastBatch: true
+  });
+
+  if (!resumed.success) {
+    console.error('Failed to resume:', resumed.message);
+    return await startFreshIndexing(projectId); // Fallback
+  }
+
+  console.log(`✅ Resumed from batch ${resumed.continueFromBatch || 0}`);
+  
+  // Продолжить обычную синхронизацию
+  const merkleHash = await computeMerkleRootHash(workspacePath);
+  return await performDeltaSync(projectId, merkleHash, {
+    resumeFromSession: resumed.sessionId
+  });
+}
+
+/**
+ * 🆕 Начать новую индексацию (с очисткой прерванных сессий)
+ */
+async function startFreshIndexing(projectId: string, clientHash?: string) {
+  // Отменить прерванные сессии если есть
+  await sdk.projects.cancelRecovery(projectId);
+  
+  // Вычислить hash если не передан
+  if (!clientHash) {
+    clientHash = await computeMerkleRootHash(workspacePath);
+  }
+
+  // Начать новую синхронизацию
+  return await performDeltaSync(projectId, clientHash);
+}
+
+/**
+ * 🧹 Полная очистка проекта (удаление всех данных)
+ */
+async function clearProjectData(projectId: string) {
+  // ВНИМАНИЕ: Это удалит ВСЕ проиндексированные данные!
+  
+  // Способ 1: Удалить проект полностью
+  await sdk.projects.deleteProject(projectId);
+  console.log('✅ Проект и все данные удалены полностью');
+  
+  // Способ 2: Очистить только файлы (оставить проект)
+  const result = await sdk.cleanupDeletedFiles(projectId, []); // Пустой список = удалить все
+  console.log(`✅ Очищено: ${result.deletedFromQdrant} векторов, ${result.deletedFromPostgres} записей`);
+}
+```
+
+### 📊 **Мониторинг прогресса индексации**
+
+```typescript
+// Real-time мониторинг через WebSocket
+await sdk.connectWebSocket();
+
+sdk.projectSync.on('sync-progress', (progress) => {
+  updateProgressBar({
+    percentage: progress.progress,
+    stage: progress.stage,
+    currentFile: progress.currentChunk,
+    totalFiles: progress.totalChunks,
+    eta: calculateETA(progress)
+  });
+});
+
+sdk.projectSync.on('sync-completed', (result) => {
+  if (result.success) {
+    showSuccessMessage(`✅ Indexing completed: ${result.totalProcessed} files processed`);
+  } else {
+    showErrorMessage(`❌ Indexing failed: ${result.errors.join(', ')}`);
+  }
+});
+
+// Периодическая проверка статуса (альтернатива WebSocket)
+const interval = setInterval(async () => {
+  const status = await sdk.projects.getDeltaSyncStatus(projectId);
+  
+  updateProgressUI({
+    progress: status.progress,
+    chunksProcessed: status.chunksProcessed,
+    totalChunks: status.totalChunks,
+    errors: status.errors
+  });
+  
+  if (status.status === 'completed' || status.status === 'failed') {
+    clearInterval(interval);
+  }
+}, 2000);
+```
+
+---
+
 ### 🔄 Delta-Chunking API (`sdk.deltaSync`)
 
 #### Синхронизация с delta-chunking
@@ -421,6 +553,151 @@ for await (const chunk of stream) {
 }
 ```
 
+---
+
+## 🛠️ **УПРАВЛЕНИЕ ДАННЫМИ ПРОЕКТА**
+
+### 🧹 **Очистка и управление файлами**
+
+```typescript
+/**
+ * 🧹 Очистка удаленных файлов (рекомендуется вызывать регулярно)
+ */
+async function cleanupDeletedFiles(projectId: string, workspacePath: string) {
+  // Получить список активных файлов в workspace
+  const activeFiles = await getWorkspaceFiles(workspacePath);
+  
+  // Очистить удаленные файлы из индекса
+  const result = await sdk.cleanupDeletedFiles(projectId, activeFiles.map(file => ({
+    filePath: file.path,
+    fileHash: file.hash,
+    lastModified: file.lastModified
+  })));
+
+  console.log(`🧹 Cleanup completed:`);
+  console.log(`  - Removed from Qdrant: ${result.deletedFromQdrant} vectors`);
+  console.log(`  - Removed from PostgreSQL: ${result.deletedFromPostgres} records`);
+  console.log(`  - Active files: ${result.activeFiles}`);
+}
+
+/**
+ * 🔄 Управление индексацией проекта
+ */
+async function manageProjectIndexing(projectId: string) {
+  // Вариант 1: Сбросить индексацию (проект остается)
+  const reset = await sdk.projects.resetIndexing(projectId);
+  console.log(`✅ Индексация сброшена: ${reset.clearedData.vectorsDeleted} векторов очищено`);
+  
+  // Вариант 2: Перезапустить индексацию (сброс + подготовка)
+  const restart = await sdk.projects.restartIndexing(projectId);
+  if (restart.readyForNewSync) {
+    console.log('✅ Готов к новой индексации');
+    // Начать новую синхронизацию
+    const hash = await computeMerkleRootHash(workspacePath);
+    await sdk.projects.initializeDeltaSync(projectId, hash);
+  }
+  
+  // Вариант 3: Очистить только удаленные файлы
+  const result = await sdk.cleanupDeletedFiles(projectId, []); // Пустой список = удалить все
+  console.log(`✅ Файлы очищены: ${result.deletedFromQdrant + result.deletedFromPostgres} записей`);
+  
+  // Вариант 4: Удалить проект полностью
+  await sdk.projects.deleteProject(projectId);
+  console.log('✅ Проект полностью удален из системы');
+}
+
+/**
+ * 🔍 Диагностика состояния проекта
+ */
+async function diagnoseProject(projectId: string) {
+  // Получить детальное состояние
+  const state = await sdk.projects.getProjectState(projectId);
+  console.log(`📊 Project State:`);
+  console.log(`  - Name: ${state.projectName}`);
+  console.log(`  - Total chunks: ${state.totalChunks}`);
+  console.log(`  - Status: ${state.indexingStatus}`);
+  console.log(`  - Last indexed: ${state.lastIndexedAt}`);
+  console.log(`  - Merkle hash: ${state.merkleRootHash?.substring(0, 8)}...`);
+
+  // Проверить прерванные сессии
+  const recovery = await sdk.projects.getRecoveryStatus(projectId);
+  if (recovery.hasInterruptedSession) {
+    const info = recovery.recoveryInfo!;
+    console.log(`⚠️ Interrupted session found:`);
+    console.log(`  - Progress: ${info.progress.percentage}% (${info.progress.processed}/${info.progress.total})`);
+    console.log(`  - Interrupted: ${info.interruptedAt}`);
+    console.log(`  - Can resume: ${info.canResume}`);
+    console.log(`  - Reason: ${info.resumeReason}`);
+  }
+
+  // Получить file mapping для отладки
+  const mapping = await sdk.projects.getFilePathMapping(projectId);
+  console.log(`📁 File mapping: ${mapping.files.length} files indexed`);
+}
+```
+
+### ⚠️ **Troubleshooting и восстановление**
+
+```typescript
+/**
+ * 🚨 Экстренное восстановление при проблемах
+ */
+async function emergencyRecovery(projectId: string) {
+  try {
+    console.log('🚨 Starting emergency recovery...');
+    
+    // 1. Проверить состояние проекта
+    const state = await sdk.projects.getProjectState(projectId);
+    console.log(`Current state: ${state.indexingStatus}`);
+    
+    // 2. Отменить все прерванные сессии
+    const cancelled = await sdk.projects.cancelRecovery(projectId);
+    if (cancelled.success) {
+      console.log('✅ Cancelled interrupted sessions');
+    }
+    
+    // 3. Очистить поврежденные данные (если нужно)
+    const cleaned = await sdk.cleanupDeletedFiles(projectId, []);
+    console.log(`🧹 Cleaned ${cleaned.deletedFromQdrant + cleaned.deletedFromPostgres} corrupted records`);
+    
+    // 4. Начать полную ресинхронизацию
+    const merkleHash = await computeMerkleRootHash(workspacePath);
+    await sdk.projects.initializeDeltaSync(projectId, merkleHash);
+    
+    console.log('✅ Emergency recovery completed, full resync started');
+    
+  } catch (error) {
+    console.error('❌ Emergency recovery failed:', error);
+    
+    // Последний шанс: удалить и пересоздать проект
+    await sdk.projects.deleteProject(projectId);
+    const newProject = await sdk.projects.createProject(projectName, projectPath);
+    console.log(`🆕 Created new project: ${newProject.id}`);
+  }
+}
+
+/**
+ * 🔄 Принудительное возобновление (для сложных случаев)
+ */
+async function forceResumeSync(projectId: string) {
+  const resumed = await sdk.projects.resumeSync(projectId, {
+    forceResume: true,          // Игнорировать canResume=false
+    skipDuplicates: true,       // Пропустить дубликаты
+    continueFromLastBatch: false // Начать сначала, но с сохраненным прогрессом
+  });
+
+  if (resumed.success) {
+    console.log('✅ Force resume successful');
+    return resumed;
+  } else {
+    console.error('❌ Force resume failed, falling back to fresh sync');
+    return await startFreshIndexing(projectId);
+  }
+}
+```
+
+---
+
 ## 💡 Рекомендации по использованию
 
 ### Real-time уведомления
@@ -584,6 +861,107 @@ sdk.projectSync.on('sync-status-update', (status) => {
 - 🔄 Delta-chunking для эффективной синхронизации
 - 🛡️ Автоматическая обработка лимитов сервера
 
+---
+
+## 📋 **QUICK REFERENCE - Управление индексацией**
+
+### 🔄 **Основные методы (обязательные для VS Code расширения)**
+
+| Метод | Описание | Когда использовать |
+|-------|----------|-------------------|
+| `getRecoveryStatus(projectId)` | Проверка прерванных сессий | При открытии проекта |
+| `getProjectState(projectId, hash?)` | Проверка актуальности | Перед синхронизацией |
+| `resumeSync(projectId, options?)` | Продолжить прерванную синхронизацию | Кнопка "Continue" |
+| `cancelRecovery(projectId)` | Отменить прерванную сессию | Кнопка "Start Fresh" |
+| `initializeDeltaSync(projectId, hash)` | Начать новую синхронизацию | Новая индексация |
+| `finalizeDeltaSync(projectId)` | Завершить синхронизацию | После отправки всех батчей |
+| `cleanupDeletedFiles(projectId, files)` | Очистить удаленные файлы | При изменении файлов |
+| `resetIndexing(projectId)` | **Сброс индексации** | Очистить данные, сохранить проект |
+| `restartIndexing(projectId)` | **Перезапуск индексации** | Сброс + подготовка к новой |
+| `deleteProject(projectId)` | **Полное удаление проекта** | Удалить проект и все данные |
+
+### 🎯 **Полный список методов управления индексацией**
+
+```typescript
+// 🔍 ПРОВЕРКА СОСТОЯНИЯ
+await sdk.projects.getProjectState(projectId, clientHash)     // Нужна ли синхронизация?
+await sdk.projects.getRecoveryStatus(projectId)              // Есть ли прерванные сессии?
+await sdk.projects.getDeltaSyncStatus(projectId)             // Текущий статус синхронизации
+
+// 🚀 УПРАВЛЕНИЕ СИНХРОНИЗАЦИЕЙ  
+await sdk.projects.initializeDeltaSync(projectId, hash)      // Начать новую синхронизацию
+await sdk.projects.resumeSync(projectId, options)           // Продолжить прерванную
+await sdk.projects.finalizeDeltaSync(projectId)             // Завершить синхронизацию
+await sdk.projects.cancelDeltaSync(projectId)               // Отменить активную синхронизацию
+
+// 🔄 УПРАВЛЕНИЕ ПРЕРЫВАНИЯМИ
+await sdk.projects.cancelRecovery(projectId)                // Отменить восстановление
+
+// 🧹 УПРАВЛЕНИЕ ДАННЫМИ
+await sdk.cleanupDeletedFiles(projectId, activeFiles)       // Очистить удаленные файлы  
+await sdk.projects.getFilePathMapping(projectId)           // Получить mapping файлов
+await sdk.projects.resetIndexing(projectId)                // Сброс индексации (проект остается)
+await sdk.projects.restartIndexing(projectId)              // Перезапуск индексации
+await sdk.projects.deleteProject(projectId)                // ПОЛНОЕ удаление проекта
+
+// 📊 МОНИТОРИНГ (WebSocket)
+sdk.projectSync.on('sync-progress', callback)              // Real-time прогресс
+sdk.projectSync.on('sync-completed', callback)             // Завершение синхронизации
+sdk.projectSync.on('sync-status-update', callback)         // Обновления статуса
+```
+
+### 🎯 **Cursor-like UX Pattern**
+
+```typescript
+// Главный workflow для VS Code расширения
+async function openProject(projectPath: string) {
+  // 1. Создать/найти проект
+  const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
+  
+  // 2. Проверить прерванные сессии
+  const recovery = await sdk.projects.getRecoveryStatus(project.id);
+  
+  if (recovery.hasInterruptedSession) {
+    // Показать диалог: "Continue indexing (67%)" или "Start fresh"
+    const choice = await vscode.window.showInformationMessage(
+      `Indexing was interrupted at ${recovery.recoveryInfo.progress.percentage}%. Continue?`,
+      'Continue', 'Start Fresh'
+    );
+    
+    if (choice === 'Continue') {
+      await sdk.projects.resumeSync(project.id);
+    } else {
+      await sdk.projects.cancelRecovery(project.id);
+    }
+  }
+  
+  // 3. Проверить нужна ли синхронизация
+  const hash = await computeMerkleRootHash(projectPath);
+  const state = await sdk.projects.getProjectState(project.id, hash);
+  
+  if (state.syncRequired) {
+    await sdk.projects.initializeDeltaSync(project.id, hash);
+  }
+}
+```
+
+### 🚨 **Error Handling Best Practices**
+
+```typescript
+// Обработка всех возможных ошибок
+try {
+  await performDeltaSync(projectId, merkleHash);
+  await sdk.projects.finalizeDeltaSync(projectId); // ОБЯЗАТЕЛЬНО!
+} catch (error) {
+  console.error('Sync failed:', error);
+  
+  // Система автоматически пометит сессию для восстановления
+  // При следующем открытии пользователь увидит "Continue indexing"
+}
+```
+
+---
+
 ## 📞 Поддержка
 
 - **GitHub**: [Issues](https://github.com/codesolver/solver-sdk/issues)
@@ -596,4 +974,17 @@ MIT License - см. [LICENSE](LICENSE) файл.
 
 ---
 
-**🚀 Code Solver SDK v5.2.0** - Создано с ❤️ для разработчиков
+**🚀 Code Solver SDK v5.6.0** - Создано с ❤️ для разработчиков
+
+### 🎯 **НОВОЕ В v5.6.0: Advanced Indexing Management**
+- 🔄 **resetIndexing()** - сброс индексации (проект остается)
+- 🚀 **restartIndexing()** - перезапуск индексации + подготовка
+- 🎯 **Гибкий контроль** - точное управление без удаления проекта
+- 📖 **Enhanced UX** - готовые паттерны для VS Code
+
+### 🎯 **v5.5.0: Resilient Sync System**
+- 🔄 **Cursor-like Recovery** - восстановление прерванных сессий
+- 📊 **Детальный прогресс** - процент завершения и ETA
+- 🛡️ **Автоматическая обработка прерываний** - сеть, падения, ошибки  
+- 🧹 **Smart Cleanup** - точная очистка удаленных файлов
+- 🎨 **Production UX** - готовые паттерны для VS Code расширений