@kadi.build/file-manager 1.0.0

package/src/providers/WatchProvider.js

@@ -0,0 +1,611 @@
+import chokidar from 'chokidar';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { EventEmitter } from 'events';
+
+class WatchProvider extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config || {};
+    this.localRoot = this.config.localRoot || process.cwd();
+    this.enabled = this.config.enabled !== false; // Default true
+    this.recursive = this.config.recursive !== false; // Default true
+    this.ignoreDotfiles = this.config.ignoreDotfiles !== false; // Default true
+    this.debounceMs = this.config.debounceMs || 100;
+    this.maxWatchers = this.config.maxWatchers || 50;
+
+    // Active watchers registry
+    this.watchers = new Map();
+    this.debounceTimers = new Map();
+    this.watchCount = 0;
+  }
+
+  // ============================================================================
+  // CONNECTION AND VALIDATION
+  // ============================================================================
+
+  async testConnection() {
+    try {
+      const stats = await fs.stat(this.localRoot);
+      if (!stats.isDirectory()) {
+        throw new Error(`Local root '${this.localRoot}' is not a directory`);
+      }
+
+      const testWatcher = chokidar.watch(this.localRoot, {
+        ignored: () => true,
+        persistent: false,
+        ignoreInitial: true
+      });
+
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error('Chokidar initialization timeout'));
+        }, 5000);
+
+        testWatcher.on('ready', () => {
+          clearTimeout(timeout);
+          testWatcher.close();
+          resolve();
+        });
+
+        testWatcher.on('error', (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        });
+      });
+
+      return {
+        provider: 'watch',
+        localRoot: this.localRoot,
+        enabled: this.enabled,
+        recursive: this.recursive,
+        activeWatchers: this.watchers.size,
+        maxWatchers: this.maxWatchers,
+        debounceMs: this.debounceMs
+      };
+    } catch (error) {
+      throw new Error(`Watch provider connection test failed: ${error.message}`);
+    }
+  }
+
+  validateConfig() {
+    const errors = [];
+    const warnings = [];
+
+    if (!this.localRoot) {
+      errors.push('Local root directory is required for watching');
+    }
+
+    if (this.debounceMs < 0) {
+      errors.push('Debounce time must be non-negative');
+    }
+
+    if (this.maxWatchers <= 0) {
+      errors.push('Max watchers must be positive');
+    }
+
+    if (this.debounceMs > 10000) {
+      warnings.push('Very high debounce time (>10s) may delay notifications significantly');
+    }
+
+    if (this.maxWatchers > 100) {
+      warnings.push('Very high max watchers (>100) may impact performance');
+    }
+
+    if (!this.enabled) {
+      warnings.push('File watching is disabled');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  // ============================================================================
+  // PATH MANAGEMENT METHODS
+  // ============================================================================
+
+  normalizePath(inputPath) {
+    if (!inputPath || inputPath === '/') {
+      return this.localRoot;
+    }
+
+    if (path.isAbsolute(inputPath)) {
+      return path.normalize(inputPath);
+    }
+
+    const resolvedLocalRoot = path.resolve(this.localRoot);
+    return path.resolve(resolvedLocalRoot, inputPath);
+  }
+
+  validatePath(inputPath) {
+    if (!inputPath) {
+      throw new Error('Path cannot be empty');
+    }
+
+    if (/[<>:"|?*\x00-\x1f]/.test(inputPath)) {
+      throw new Error(`Path contains invalid characters: ${inputPath}`);
+    }
+
+    return true;
+  }
+
+  generateWatchId(watchPath, options = {}) {
+    const normalizedPath = this.normalizePath(watchPath);
+    const optionsHash = JSON.stringify(options);
+    return `${normalizedPath}:${optionsHash}`;
+  }
+
+  // ============================================================================
+  // CORE WATCHING METHODS
+  // ============================================================================
+
+  async startWatching(watchPath, options = {}) {
+    this.validatePath(watchPath);
+
+    if (!this.enabled) {
+      throw new Error('File watching is disabled in configuration');
+    }
+
+    const normalizedPath = this.normalizePath(watchPath);
+
+    // Check if path exists
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isDirectory() && !stats.isFile()) {
+        throw new Error(`Path '${watchPath}' is neither a file nor directory`);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`Path not found: ${watchPath}`);
+      }
+      throw error;
+    }
+
+    const watchId = this.generateWatchId(watchPath, options);
+
+    // Check if already watching
+    if (this.watchers.has(watchId)) {
+      return {
+        watchId,
+        path: watchPath,
+        alreadyWatching: true
+      };
+    }
+
+    // Check watcher limit
+    if (this.watchCount >= this.maxWatchers) {
+      throw new Error(`Maximum number of watchers (${this.maxWatchers}) reached`);
+    }
+
+    const {
+      recursive = this.recursive,
+      ignoreDotfiles = this.ignoreDotfiles,
+      events = ['add', 'change', 'unlink', 'addDir', 'unlinkDir'],
+      callback = null,
+      persistent = true
+    } = options;
+
+    try {
+      const ignorePattern = this.buildIgnorePattern(ignoreDotfiles, recursive, normalizedPath);
+
+      const watcher = chokidar.watch(normalizedPath, {
+        ignored: ignorePattern,
+        persistent: persistent,
+        ignoreInitial: true,
+        followSymlinks: false,
+        disableGlobbing: true,
+        usePolling: false,
+        interval: 100,
+        binaryInterval: 300,
+        ignorePermissionErrors: true
+      });
+
+      // Set up event handlers
+      this.setupWatcherEvents(watcher, watchId, watchPath, events, callback);
+
+      // Wait for watcher to be ready
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error('Watcher initialization timeout'));
+        }, 10000);
+
+        watcher.on('ready', () => {
+          clearTimeout(timeout);
+          resolve();
+        });
+
+        watcher.on('error', (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        });
+      });
+
+      // Store watcher info
+      this.watchers.set(watchId, {
+        watcher,
+        path: watchPath,
+        normalizedPath,
+        options: {
+          recursive: recursive,
+          ignoreDotfiles: ignoreDotfiles,
+          events: events,
+          persistent: persistent
+        },
+        callback,
+        startedAt: new Date().toISOString(),
+        eventCount: 0
+      });
+
+      this.watchCount++;
+
+      return {
+        watchId,
+        path: watchPath,
+        recursive,
+        events,
+        startedAt: new Date().toISOString()
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to start watching ${watchPath}: ${error.message}`);
+    }
+  }
+
+  async stopWatching(watchIdOrPath) {
+    let watchId;
+
+    if (this.watchers.has(watchIdOrPath)) {
+      watchId = watchIdOrPath;
+    } else {
+      watchId = this.findWatcherByPath(watchIdOrPath);
+      if (!watchId) {
+        throw new Error(`No active watcher found for: ${watchIdOrPath}`);
+      }
+    }
+
+    const watcherInfo = this.watchers.get(watchId);
+    if (!watcherInfo) {
+      throw new Error(`Watcher not found: ${watchId}`);
+    }
+
+    try {
+      await watcherInfo.watcher.close();
+
+      this.cleanupDebounceTimers(watchId);
+
+      this.watchers.delete(watchId);
+      this.watchCount--;
+
+      return {
+        watchId,
+        path: watcherInfo.path,
+        stopped: true,
+        eventCount: watcherInfo.eventCount,
+        duration: Date.now() - new Date(watcherInfo.startedAt).getTime()
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to stop watching: ${error.message}`);
+    }
+  }
+
+  async stopAllWatching() {
+    const results = [];
+    const watchIds = Array.from(this.watchers.keys());
+
+    for (const watchId of watchIds) {
+      try {
+        const result = await this.stopWatching(watchId);
+        results.push(result);
+      } catch (error) {
+        results.push({
+          watchId,
+          error: error.message
+        });
+      }
+    }
+
+    this.debounceTimers.clear();
+
+    return {
+      stopped: results.filter(r => r.stopped).length,
+      failed: results.filter(r => r.error).length,
+      results
+    };
+  }
+
+  // ============================================================================
+  // WATCHER MANAGEMENT METHODS
+  // ============================================================================
+
+  setupWatcherEvents(watcher, watchId, watchPath, events, callback) {
+    const eventHandlers = {
+      add: (filePath) => this.handleFileEvent('add', filePath, watchId, watchPath, callback),
+      change: (filePath) => this.handleFileEvent('change', filePath, watchId, watchPath, callback),
+      unlink: (filePath) => this.handleFileEvent('unlink', filePath, watchId, watchPath, callback),
+      addDir: (dirPath) => this.handleFileEvent('addDir', dirPath, watchId, watchPath, callback),
+      unlinkDir: (dirPath) => this.handleFileEvent('unlinkDir', dirPath, watchId, watchPath, callback)
+    };
+
+    events.forEach(eventType => {
+      if (eventHandlers[eventType]) {
+        watcher.on(eventType, eventHandlers[eventType]);
+      }
+    });
+
+    watcher.on('error', (error) => {
+      this.emit('watcherError', {
+        watchId,
+        path: watchPath,
+        error: error.message
+      });
+    });
+  }
+
+  handleFileEvent(eventType, filePath, watchId, watchPath, callback) {
+    const watcherInfo = this.watchers.get(watchId);
+    if (!watcherInfo) {
+      return;
+    }
+
+    // Non-recursive safety filter
+    const isNonRecursive = watcherInfo.options.recursive === false;
+
+    if (isNonRecursive) {
+      const watchedPath = path.resolve(watcherInfo.normalizedPath);
+      const eventPath = path.resolve(filePath);
+      const eventParentDir = path.dirname(eventPath);
+
+      if (eventParentDir !== watchedPath) {
+        return; // Block nested events
+      }
+    }
+
+    // Increment event counter
+    watcherInfo.eventCount = (watcherInfo.eventCount || 0) + 1;
+
+    // Create event data
+    const eventData = {
+      type: eventType,
+      path: filePath,
+      relativePath: path.relative(watcherInfo.normalizedPath, filePath),
+      watchId,
+      watchPath,
+      timestamp: new Date().toISOString()
+    };
+
+    // Apply debouncing
+    if (this.debounceMs > 0) {
+      this.debounceEvent(eventData, callback);
+    } else {
+      this.processEvent(eventData, callback);
+    }
+  }
+
+  debounceEvent(eventData, callback) {
+    const debounceKey = `${eventData.watchId}:${eventData.path}:${eventData.type}`;
+
+    if (this.debounceTimers.has(debounceKey)) {
+      clearTimeout(this.debounceTimers.get(debounceKey));
+    }
+
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(debounceKey);
+      this.processEvent(eventData, callback);
+    }, this.debounceMs);
+
+    this.debounceTimers.set(debounceKey, timer);
+  }
+
+  processEvent(eventData, callback) {
+    this.emit('fileEvent', eventData);
+
+    if (callback && typeof callback === 'function') {
+      try {
+        callback(eventData);
+      } catch (error) {
+        this.emit('watcherError', {
+          watchId: eventData.watchId,
+          path: eventData.path,
+          error: `Callback error: ${error.message}`
+        });
+      }
+    }
+  }
+
+  // ============================================================================
+  // UTILITY AND QUERY METHODS
+  // ============================================================================
+
+  buildIgnorePattern(ignoreDotfiles, isRecursive = true, watchedPath = null) {
+    const patterns = [];
+
+    if (ignoreDotfiles) {
+      patterns.push(/(^|[\/\\])\../);
+    }
+
+    // Always ignore common system files
+    patterns.push(/node_modules/);
+    patterns.push(/\.git/);
+    patterns.push(/\.DS_Store/);
+    patterns.push(/Thumbs\.db/);
+
+    // For non-recursive, add a pattern that ignores anything in subdirectories
+    if (!isRecursive && watchedPath) {
+      const resolvedWatchedPath = path.resolve(watchedPath);
+      const nestedPattern = new RegExp(
+        resolvedWatchedPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+        '[\\\\/][^\\\\\/]+[\\\\/]'
+      );
+      patterns.push(nestedPattern);
+    }
+
+    return patterns.length > 0 ? patterns : null;
+  }
+
+  findWatcherByPath(searchPath) {
+    const normalizedSearch = this.normalizePath(searchPath);
+
+    for (const [watchId, watcherInfo] of this.watchers) {
+      if (watcherInfo.normalizedPath === normalizedSearch ||
+        watcherInfo.path === searchPath) {
+        return watchId;
+      }
+    }
+
+    return null;
+  }
+
+  cleanupDebounceTimers(watchId) {
+    const keysToDelete = [];
+
+    for (const [key, timer] of this.debounceTimers) {
+      if (key.startsWith(watchId + ':')) {
+        clearTimeout(timer);
+        keysToDelete.push(key);
+      }
+    }
+
+    keysToDelete.forEach(key => this.debounceTimers.delete(key));
+  }
+
+  getEventIcon(eventType) {
+    const icons = {
+      add: '📄',
+      change: '✏️',
+      unlink: '🗑️',
+      addDir: '📁',
+      unlinkDir: '🗂️'
+    };
+    return icons[eventType] || '📋';
+  }
+
+  // ============================================================================
+  // INFORMATION AND STATUS METHODS
+  // ============================================================================
+
+  listActiveWatchers() {
+    const watchers = [];
+
+    for (const [watchId, watcherInfo] of this.watchers) {
+      watchers.push({
+        watchId,
+        path: watcherInfo.path,
+        recursive: watcherInfo.options.recursive,
+        events: watcherInfo.options.events,
+        startedAt: watcherInfo.startedAt,
+        eventCount: watcherInfo.eventCount || 0,
+        duration: Date.now() - new Date(watcherInfo.startedAt).getTime()
+      });
+    }
+
+    return watchers;
+  }
+
+  getWatcherInfo(watchIdOrPath) {
+    let watchId;
+
+    if (this.watchers.has(watchIdOrPath)) {
+      watchId = watchIdOrPath;
+    } else {
+      watchId = this.findWatcherByPath(watchIdOrPath);
+      if (!watchId) {
+        throw new Error(`Watcher not found: ${watchIdOrPath}`);
+      }
+    }
+
+    const watcherInfo = this.watchers.get(watchId);
+    if (!watcherInfo) {
+      throw new Error(`Watcher not found: ${watchId}`);
+    }
+
+    return {
+      watchId,
+      path: watcherInfo.path,
+      normalizedPath: watcherInfo.normalizedPath,
+      options: watcherInfo.options,
+      startedAt: watcherInfo.startedAt,
+      eventCount: watcherInfo.eventCount || 0,
+      duration: Date.now() - new Date(watcherInfo.startedAt).getTime(),
+      hasCallback: !!watcherInfo.callback
+    };
+  }
+
+  getWatchingStatus() {
+    return {
+      enabled: this.enabled,
+      activeWatchers: this.watchers.size,
+      maxWatchers: this.maxWatchers,
+      totalEvents: Array.from(this.watchers.values()).reduce((sum, w) => sum + (w.eventCount || 0), 0),
+      pendingDebounces: this.debounceTimers.size,
+      config: {
+        recursive: this.recursive,
+        ignoreDotfiles: this.ignoreDotfiles,
+        debounceMs: this.debounceMs
+      }
+    };
+  }
+
+  // ============================================================================
+  // ERROR HANDLING HELPERS
+  // ============================================================================
+
+  isPathNotFoundError(error) {
+    return error.code === 'ENOENT' ||
+      error.message.includes('not found') ||
+      error.message.includes('no such file');
+  }
+
+  isPermissionError(error) {
+    return error.code === 'EACCES' ||
+      error.code === 'EPERM' ||
+      error.message.includes('permission denied');
+  }
+
+  isWatchingError(error) {
+    return error.message.includes('watch') ||
+      error.message.includes('EMFILE') ||
+      error.message.includes('ENOSPC');
+  }
+
+  // ============================================================================
+  // CLEANUP AND SHUTDOWN
+  // ============================================================================
+
+  async shutdown() {
+    try {
+      const result = await this.stopAllWatching();
+      this.removeAllListeners();
+      return result;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  formatBytes(bytes) {
+    if (bytes === 0) return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+  }
+
+  formatDuration(milliseconds) {
+    const seconds = Math.floor(milliseconds / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+    } else if (minutes > 0) {
+      return `${minutes}m ${seconds % 60}s`;
+    } else {
+      return `${seconds}s`;
+    }
+  }
+}
+
+export { WatchProvider };