@arela/uploader 0.2.13 → 1.0.0

package/src/commands/WatchCommand.js

@@ -0,0 +1,1342 @@
+import cliProgress from 'cli-progress';
+import { randomUUID } from 'crypto';
+import FormData from 'form-data';
+import fs from 'fs';
+import mime from 'mime-types';
+import path from 'path';
+
+import databaseService from '../services/DatabaseService.js';
+import logger from '../services/LoggingService.js';
+import { createSignalHandler } from '../services/SignalHandler.js';
+import watchService from '../services/WatchService.js';
+import uploadServiceFactory from '../services/upload/UploadServiceFactory.js';
+
+import appConfig from '../config/config.js';
+import ErrorHandler from '../errors/ErrorHandler.js';
+import { cleanupManager } from '../utils/CleanupManager.js';
+import FileOperations from '../utils/FileOperations.js';
+import fileSanitizer from '../utils/FileSanitizer.js';
+import watchEventHandler from '../utils/WatchEventHandler.js';
+import UploadCommand from './UploadCommand.js';
+
+/**
+ * Watch Command Handler
+ * Monitors directories for changes and triggers uploads
+ */
+export class WatchCommand {
+  constructor() {
+    this.errorHandler = new ErrorHandler(logger);
+    this.uploadCommand = new UploadCommand();
+    this.uploadService = null;
+    this.databaseService = databaseService;
+    this.isShuttingDown = false;
+
+    // Progress bars tracking
+    this.progressBars = null;
+    this.progressMetrics = {
+      individual: { start: null, processed: 0, total: 0 },
+      batch: { start: null, processed: 0, total: 0 },
+      'full-structure': { start: null, processed: 0, total: 0 },
+    };
+
+    // Upload statistics tracking
+    this.uploadStats = {
+      totalUploads: 0,
+      totalFiles: 0,
+      successCount: 0,
+      failureCount: 0,
+      retryCount: 0,
+      lastUploadTime: null,
+      uploadDetails: [],
+    };
+
+    // Signal handling
+    this.signalHandler = createSignalHandler(logger, cleanupManager);
+    this.sessionId = null;
+  }
+
+  /**
+   * Execute the watch command
+   * @param {Object} options - Command options
+   * @returns {Promise<void>}
+   */
+  async execute(options) {
+    try {
+      // Validate configuration
+      this.#validateOptions(options); // TDOO: Looks like this function is empty
+
+      // Parse directories to watch
+      const directories = this.#parseDirectories(options.directories);
+
+      if (directories.length === 0) {
+        throw new Error(
+          'No directories specified. Use --directories or WATCH_DIRECTORIES env var',
+        );
+      }
+
+      // Validate watch configuration
+      try {
+        appConfig.validateWatchConfig(directories);
+      } catch (error) {
+        logger.error(`Configuration error: ${error.message}`);
+        throw error;
+      }
+
+      // Parse watch options
+      const watchOptions = this.#parseWatchOptions(options);
+
+      // Clear log if requested
+      if (options.clearLog) {
+        logger.clearLogFile();
+        logger.info('Log file cleared');
+      }
+
+      // Initialize upload service
+      // In cross-tenant mode, use the sourceApi for initial connection check
+      // In single API mode, use the specified API target or default
+      try {
+        if (appConfig.isCrossTenantMode()) {
+          // Cross-tenant mode: use sourceApi for the upload service
+          this.uploadService =
+            await uploadServiceFactory.getApiServiceForTarget(
+              appConfig.api.sourceTarget,
+            );
+          logger.info(
+            `Upload service initialized for cross-tenant mode (source: ${appConfig.api.sourceTarget})`,
+          );
+        } else if (
+          appConfig.api.activeTarget &&
+          appConfig.api.activeTarget !== 'default'
+        ) {
+          // Single API mode with specific target
+          this.uploadService =
+            await uploadServiceFactory.getApiServiceForTarget(
+              appConfig.api.activeTarget,
+            );
+          logger.info(
+            `Upload service initialized for API target: ${appConfig.api.activeTarget}`,
+          );
+        } else {
+          // Default mode
+          this.uploadService = await uploadServiceFactory.getUploadService(
+            options.forceSupabase,
+          );
+          logger.info(
+            `Upload service initialized: ${this.uploadService.getServiceName()}`,
+          );
+        }
+      } catch (error) {
+        logger.error(`Failed to initialize upload service: ${error.message}`);
+        throw error;
+      }
+
+      // Reset upload statistics
+      this.uploadStats = {
+        totalUploads: 0,
+        totalFiles: 0,
+        successCount: 0,
+        failureCount: 0,
+        retryCount: 0,
+        lastUploadTime: null,
+        uploadDetails: [],
+      };
+
+      // Initialize session tracking
+      const sessionId = randomUUID();
+      logger.initializeSession(sessionId);
+
+      // Initialize progress bars
+      this.#initializeProgressBars();
+
+      // Log startup
+      logger.info('═══════════════════════════════════════════════════════');
+      logger.info('🟢 WATCH MODE STARTED');
+      logger.info('═══════════════════════════════════════════════════════');
+      logger.info(`📁 Watching ${directories.length} director(y/ies):`);
+      directories.forEach((dirConfig) => {
+        const dirPath = dirConfig.path || dirConfig;
+        const folderStructure = dirConfig.folderStructure || 'default';
+        logger.info(
+          `   → ${path.resolve(dirPath)} [structure: ${folderStructure}]`,
+        );
+      });
+      logger.info(`🎯 Strategy: ${watchOptions.strategy}`);
+      logger.info(`⏱️ Debounce: ${watchOptions.debounceMs}ms`);
+      logger.info(`📦 Batch size: ${watchOptions.batchSize}`);
+      logger.info('═══════════════════════════════════════════════════════\n');
+
+      // Initialize watchers with directory configurations
+      for (const dirConfig of directories) {
+        const dirPath = dirConfig.path || dirConfig;
+        await watchService.addWatcher(
+          dirPath,
+          {
+            usePolling: watchOptions.usePolling,
+            interval: watchOptions.interval,
+            stabilityThreshold: watchOptions.stabilityThreshold,
+            ignored: this.#parseIgnorePatterns(options.ignore),
+          },
+          dirConfig,
+        );
+      }
+
+      // Enable auto-processing if configured
+      if (options.autoProcessing !== false) {
+        watchService.enableAutoProcessing({
+          batchSize: watchOptions.batchSize,
+        });
+        logger.info('🔄 Auto-processing pipeline enabled');
+      }
+
+      // Set event handler with directory configurations
+      watchService.setEventHandler(async (eventType, filePath) => {
+        await this.#handleFileEvent(
+          eventType,
+          filePath,
+          options,
+          watchOptions,
+          directories,
+        );
+      });
+
+      // Start watching
+      await watchService.start();
+
+      // Wait for all watchers to complete initial scan before processing
+      await watchService.waitForWatchersReady();
+
+      // Setup signal handlers for graceful shutdown
+      this.#setupSignalHandlers();
+
+      // Keep process alive
+      logger.info('💡 Press Ctrl+C to stop watching\n');
+      await this.#keepProcessAlive();
+    } catch (error) {
+      this.errorHandler.handleFatalError(error, { command: 'watch' });
+    }
+  }
+
+  /**
+   * Handle file events
+   * @private
+   * @param {string} eventType - Type of event
+   * @param {string} filePath - Path to file
+   * @param {Object} options - Command options
+   * @param {Object} watchOptions - Parsed watch options
+   * @param {Array<Object>} directories - Array of directory configurations
+   * @returns {Promise<void>}
+   */
+  async #handleFileEvent(
+    eventType,
+    filePath,
+    options,
+    watchOptions,
+    directories = [],
+  ) {
+    try {
+      // Skip if dry-run
+      if (options.dryRun) {
+        logger.info(`[DRY RUN] Would upload: ${filePath}`);
+        return;
+      }
+
+      // Skip remove events
+      if (eventType === 'remove' || eventType === 'unlink') {
+        logger.debug(`Skipping file removal event: ${filePath}`);
+        return;
+      }
+
+      // Skip if auto-processing is enabled (it handles file processing)
+      if (options.autoProcessing !== false) {
+        logger.debug(
+          `[AutoProcessing] File event skipped (auto-processing is handling it): ${filePath}`,
+        );
+        return;
+      }
+
+      // Find which directory this file belongs to
+      const watchDir = this.#findWatchDirectory(filePath, directories);
+      const folderStructure = watchDir?.folderStructure || 'default';
+
+      // Execute upload based on strategy
+      switch (watchOptions.strategy) {
+        case 'individual':
+          try {
+            await this.#uploadIndividual(filePath, options);
+          } catch (strategyError) {
+            logger.error(
+              `Error in individual upload: ${strategyError.message}`,
+            );
+            throw strategyError;
+          }
+          break;
+        case 'batch':
+          try {
+            await this.#uploadBatch(
+              filePath,
+              options,
+              watchOptions,
+              directories,
+            );
+          } catch (strategyError) {
+            logger.error(`Error in batch upload: ${strategyError.message}`);
+            throw strategyError;
+          }
+          break;
+        case 'full-structure':
+          try {
+            await this.#uploadFullStructure(
+              filePath,
+              options,
+              watchOptions,
+              directories,
+            );
+          } catch (strategyError) {
+            logger.error(
+              `Error in full-structure upload: ${strategyError.message}`,
+            );
+            throw strategyError;
+          }
+          break;
+        default:
+          logger.warn(`Unknown strategy: ${watchOptions.strategy}`);
+      }
+
+      // Increment upload counter
+      const stats = watchService.getStats();
+      logger.info(
+        `📊 Stats: +${stats.filesAdded} files, +${stats.filesModified} modified`,
+      );
+    } catch (error) {
+      logger.error(`Error handling file event: ${error.message}`);
+      logger.error(`Stack: ${error.stack}`);
+      // Log the full error for debugging
+      if (error.code) {
+        logger.debug(`Error code: ${error.code}`);
+      }
+    }
+  }
+
+  /**
+   * Find which watch directory a file belongs to
+   * @private
+   * @param {string} filePath - Path to file
+   * @param {Array<Object>} directories - Array of directory configurations
+   * @returns {Object|null} Directory configuration or null
+   */
+  #findWatchDirectory(filePath, directories) {
+    const normalizedFilePath = path.resolve(filePath);
+
+    for (const dirConfig of directories) {
+      const dirPath = dirConfig.path || dirConfig;
+      const normalizedDirPath = path.resolve(dirPath);
+
+      if (normalizedFilePath.startsWith(normalizedDirPath)) {
+        return dirConfig;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Retry upload with exponential backoff
+   * @private
+   * @param {Function} uploadFn - Function that performs the upload
+   * @param {number} maxRetries - Maximum number of retries
+   * @param {number} initialBackoffMs - Initial backoff in milliseconds
+   * @returns {Promise<any>} Upload result
+   * @throws {Error} If all retries fail
+   */
+  async #retryUpload(uploadFn, maxRetries = 3, initialBackoffMs = 1000) {
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await uploadFn();
+      } catch (error) {
+        lastError = error;
+
+        if (attempt === maxRetries) {
+          throw error;
+        }
+
+        const backoffMs = initialBackoffMs * Math.pow(2, attempt - 1);
+        logger.warn(
+          `Upload failed (attempt ${attempt}/${maxRetries}), retrying in ${backoffMs}ms: ${error.message}`,
+        );
+
+        this.uploadStats.retryCount++;
+
+        // Wait before retrying
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Prepare a file for upload with metadata
+   * @private
+   * @param {string} filePath - Absolute path to file
+   * @param {Object} options - Command options
+   * @returns {Object} File object for upload
+   */
+  #prepareFileForUpload(filePath, options) {
+    const stats = FileOperations.getFileStats(filePath);
+
+    return {
+      path: filePath,
+      name: path.basename(filePath),
+      relativePath: path.basename(filePath),
+      contentType: mime.lookup(filePath) || 'application/octet-stream',
+      size: stats?.size || 0,
+      metadata: {
+        source: 'watch-mode',
+        timestamp: new Date().toISOString(),
+        watchSource: path.dirname(filePath),
+      },
+    };
+  }
+
+  /**
+   * Upload individual file
+   * @private
+   * @param {string} filePath - File path to upload
+   * @param {Object} options - Command options
+   * @returns {Promise<void>}
+   */
+  async #uploadIndividual(filePath, options) {
+    const startTime = Date.now();
+    try {
+      logger.info(`📤 [INDIVIDUAL] Uploading: ${filePath}`);
+
+      // Get file object from event handler
+      const files = await watchEventHandler.getFilesForUpload('individual', {
+        sourceDir: path.dirname(filePath),
+      });
+
+      if (files.length === 0) {
+        logger.warn(`No valid files to upload for: ${filePath}`);
+        return;
+      }
+
+      const file = files[0];
+      logger.info(`   File: ${file.name} (${this.#formatFileSize(file.size)})`);
+
+      // Validate file exists and is accessible
+      if (!FileOperations.fileExists(file.path)) {
+        throw new Error(`File not accessible: ${file.path}`);
+      }
+
+      // ✅ CRITICAL: Validate file has been evaluated by watcher
+      const validatedFiles = this.#validateFilesAreWatched([file]);
+      if (validatedFiles.length === 0) {
+        logger.warn(
+          `⚠️  File was not properly evaluated by watcher: ${file.name}`,
+        );
+        this.uploadStats.failureCount++;
+        this.uploadStats.uploadDetails.push({
+          timestamp: new Date().toISOString(),
+          fileName: file.name,
+          strategy: 'individual',
+          status: 'rejected',
+          reason: 'Not evaluated by watcher',
+          duration: Date.now() - startTime,
+        });
+        return;
+      }
+
+      // Prepare file for upload with metadata
+      const fileForUpload = this.#prepareFileForUpload(file.path, options);
+
+      // Create upload with retries
+      const result = await this.#retryUpload(
+        async () => {
+          const uploadResult = await this.uploadService.upload(
+            [fileForUpload],
+            {
+              strategy: 'individual',
+              sourceType: 'watch-mode',
+            },
+          );
+          return uploadResult;
+        },
+        3,
+        1000,
+      );
+
+      // Update statistics
+      this.uploadStats.totalUploads++;
+      this.uploadStats.totalFiles++;
+      this.uploadStats.successCount++;
+      this.uploadStats.lastUploadTime = new Date();
+
+      // Record upload details
+      this.uploadStats.uploadDetails.push({
+        timestamp: new Date().toISOString(),
+        fileName: file.name,
+        size: file.size,
+        strategy: 'individual',
+        status: 'success',
+        duration: Date.now() - startTime,
+      });
+
+      logger.info(`✅ Upload successful: ${file.name}`);
+      watchService.stats.uploadsTriggered++;
+    } catch (error) {
+      this.uploadStats.failureCount++;
+      logger.error(`❌ Error uploading individual file: ${error.message}`);
+
+      // Record failed upload
+      this.uploadStats.uploadDetails.push({
+        timestamp: new Date().toISOString(),
+        fileName: path.basename(filePath),
+        strategy: 'individual',
+        status: 'failed',
+        error: error.message,
+        duration: Date.now() - startTime,
+      });
+    }
+  }
+
+  /**
+   * Upload batch of files
+   * @private
+   * @param {string} filePath - Triggering file path
+   * @param {Object} options - Command options
+   * @param {Object} watchOptions - Watch options
+   * @returns {Promise<void>}
+   */
+  /**
+   * Upload batch of files
+   * @private
+   * @param {string} filePath - Triggering file path
+   * @param {Object} options - Command options
+   * @param {Object} watchOptions - Watch options
+   * @param {Array<Object>} directories - Array of directory configurations
+   * @returns {Promise<void>}
+   */
+  async #uploadBatch(filePath, options, watchOptions, directories = []) {
+    const startTime = Date.now();
+    try {
+      logger.info(`📤 [BATCH] Upload triggered by: ${filePath}`);
+
+      // Find the watch directory for this file
+      const watchDirConfig = this.#findWatchDirectory(filePath, directories);
+      const folderStructure = watchDirConfig?.folderStructure || 'default';
+
+      // Get batch of files from event handler
+      const files = await watchEventHandler.getFilesForUpload('batch', {
+        batchSize: watchOptions.batchSize,
+        sourceDir: path.dirname(filePath),
+      });
+
+      if (files.length === 0) {
+        logger.warn('No valid files found for batch upload');
+        return;
+      }
+
+      // Log batch details
+      logger.info(`   Batch size: ${files.length} files`);
+      logger.info(`   Folder structure: ${folderStructure}`);
+      let totalSize = 0;
+      files.forEach((file) => {
+        totalSize += file.size;
+        logger.debug(`   - ${file.name} (${this.#formatFileSize(file.size)})`);
+      });
+
+      logger.info(`   Total size: ${this.#formatFileSize(totalSize)}`);
+
+      // Validate all files exist
+      const invalidFiles = files.filter(
+        (f) => !FileOperations.fileExists(f.path),
+      );
+      if (invalidFiles.length > 0) {
+        throw new Error(`${invalidFiles.length} file(s) not accessible`);
+      }
+
+      // ✅ CRITICAL: Validate files have been evaluated by watcher
+      const validatedFiles = this.#validateFilesAreWatched(files);
+      if (validatedFiles.length === 0) {
+        logger.warn(
+          `⚠️  None of the ${files.length} files were properly evaluated by watcher`,
+        );
+        this.uploadStats.failureCount += files.length;
+        this.uploadStats.uploadDetails.push({
+          timestamp: new Date().toISOString(),
+          fileCount: files.length,
+          strategy: 'batch',
+          status: 'rejected',
+          reason: 'No files evaluated by watcher',
+          duration: Date.now() - startTime,
+        });
+        return;
+      }
+
+      if (validatedFiles.length < files.length) {
+        logger.warn(
+          `⚠️  Only ${validatedFiles.length}/${files.length} files were properly evaluated by watcher. Uploading only validated files.`,
+        );
+      }
+
+      // Prepare files for upload
+      const filesForUpload = validatedFiles.map((f) =>
+        this.#prepareFileForUpload(f.path, options),
+      );
+
+      // Create upload with retries
+      const result = await this.#retryUpload(
+        async () => {
+          const uploadResult = await this.uploadService.upload(filesForUpload, {
+            strategy: 'batch',
+            batchSize: watchOptions.batchSize,
+            sourceType: 'watch-mode',
+          });
+          return uploadResult;
+        },
+        3,
+        1000,
+      );
+
+      // Update statistics
+      this.uploadStats.totalUploads++;
+      this.uploadStats.totalFiles += files.length;
+      this.uploadStats.successCount += files.length;
+      this.uploadStats.lastUploadTime = new Date();
+
+      // Record upload details
+      this.uploadStats.uploadDetails.push({
+        timestamp: new Date().toISOString(),
+        fileCount: files.length,
+        strategy: 'batch',
+        folderStructure,
+        status: 'success',
+        duration: Date.now() - startTime,
+      });
+
+      logger.info(`✅ Batch upload successful: ${files.length} files`);
+      watchService.stats.uploadsTriggered++;
+
+      // Clear processed events
+      watchEventHandler.clearProcessed();
+    } catch (error) {
+      this.uploadStats.failureCount += files?.length || 1;
+      logger.error(`❌ Error uploading batch: ${error.message}`);
+
+      // Record failed upload
+      this.uploadStats.uploadDetails.push({
+        timestamp: new Date().toISOString(),
+        strategy: 'batch',
+        status: 'failed',
+        error: error.message,
+        duration: Date.now() - startTime,
+      });
+    }
+  }
+
+  /**
+   * Upload full directory structure
+   * @private
+   * @param {string} filePath - Triggering file path
+   * @param {Object} options - Command options
+   * @param {Object} watchOptions - Watch options
+   * @param {Array<Object>} directories - Array of directory configurations
+   * @returns {Promise<void>}
+   */
+  async #uploadFullStructure(
+    filePath,
+    options,
+    watchOptions,
+    directories = [],
+  ) {
+    const startTime = Date.now();
+    try {
+      logger.info(`📤 [FULL-STRUCTURE] Upload triggered by: ${filePath}`);
+
+      // Find the watch directory for this file
+      const watchDirConfig = this.#findWatchDirectory(filePath, directories);
+      const folderStructure = watchDirConfig?.folderStructure || 'default';
+
+      // Get full structure from event handler
+      const files = await watchEventHandler.getFilesForUpload(
+        'full-structure',
+        {
+          sourceDir: path.dirname(filePath),
+        },
+      );
+
+      if (files.length === 0) {
+        logger.warn('No valid files found for full structure upload');
+        return;
+      }
+
+      // Log structure details
+      logger.info(`   Structure size: ${files.length} files`);
+      logger.info(`   Folder structure: ${folderStructure}`);
+      let totalSize = 0;
+      const directoriesInStructure = new Set();
+
+      files.forEach((file) => {
+        totalSize += file.size;
+        const dir = path.dirname(file.path);
+        directoriesInStructure.add(dir);
+      });
+
+      logger.info(`   Directories: ${directoriesInStructure.size}`);
+      logger.info(`   Total size: ${this.#formatFileSize(totalSize)}`);
+
+      // Validate all files exist
+      const invalidFiles = files.filter(
+        (f) => !FileOperations.fileExists(f.path),
+      );
+      if (invalidFiles.length > 0) {
+        throw new Error(
+          `${invalidFiles.length} file(s) not accessible in structure`,
+        );
+      }
+
+      // ✅ CRITICAL: Validate files have been evaluated by watcher
+      const validatedFiles = this.#validateFilesAreWatched(files);
+      if (validatedFiles.length === 0) {
+        logger.warn(
+          `⚠️  None of the ${files.length} files were properly evaluated by watcher`,
+        );
+        this.uploadStats.failureCount += files.length;
+        this.uploadStats.uploadDetails.push({
+          timestamp: new Date().toISOString(),
+          fileCount: files.length,
+          strategy: 'full-structure',
+          status: 'rejected',
+          reason: 'No files evaluated by watcher',
+          duration: Date.now() - startTime,
+        });
+        return;
+      }
+
+      if (validatedFiles.length < files.length) {
+        logger.warn(
+          `⚠️  Only ${validatedFiles.length}/${files.length} files were properly evaluated by watcher. Uploading only validated files.`,
+        );
+      }
+
+      // Prepare files for upload
+      const filesForUpload = validatedFiles.map((f) =>
+        this.#prepareFileForUpload(f.path, options),
+      );
+
+      // Create upload with retries
+      const result = await this.#retryUpload(
+        async () => {
+          const uploadResult = await this.uploadService.upload(filesForUpload, {
+            strategy: 'full-structure',
+            sourceType: 'watch-mode',
+            metadata: {
+              totalFiles: files.length,
+              totalDirectories: directoriesInStructure.size,
+              totalSize: totalSize,
+              folderStructure: folderStructure,
+            },
+          });
+          return uploadResult;
+        },
+        3,
+        1000,
+      );
+
+      // Update statistics
+      this.uploadStats.totalUploads++;
+      this.uploadStats.totalFiles += files.length;
+      this.uploadStats.successCount += files.length;
+      this.uploadStats.lastUploadTime = new Date();
+
+      // Record upload details
+      this.uploadStats.uploadDetails.push({
+        timestamp: new Date().toISOString(),
+        fileCount: files.length,
+        dirCount: directories.size,
+        strategy: 'full-structure',
+        status: 'success',
+        duration: Date.now() - startTime,
+      });
+
+      logger.info(
+        `✅ Full structure upload successful: ${files.length} files in ${directories.size} directories`,
+      );
+      watchService.stats.uploadsTriggered++;
+
+      // Clear processed events
+      watchEventHandler.clearProcessed();
+    } catch (error) {
+      this.uploadStats.failureCount += files?.length || 1;
+      logger.error(`❌ Error uploading full structure: ${error.message}`);
+
+      // Record failed upload
+      this.uploadStats.uploadDetails.push({
+        timestamp: new Date().toISOString(),
+        strategy: 'full-structure',
+        status: 'failed',
+        error: error.message,
+        duration: Date.now() - startTime,
+      });
+    }
+  }
+
+  /**
+   * Validate that files have been properly evaluated by the watcher
+   * CRITICAL: Ensures NO files are uploaded without watcher evaluation
+   * @private
+   * @param {Array<Object>} files - Files to validate
+   * @returns {Array<Object>} Only files that have been evaluated by watcher
+   */
+  #validateFilesAreWatched(files) {
+    if (!files || files.length === 0) {
+      return [];
+    }
+
+    // Get watched directories from WatchService
+    const watchedDirs = watchService.getWatchedDirs();
+
+    if (!watchedDirs || watchedDirs.length === 0) {
+      logger.warn(
+        '⚠️  No directories are being watched. Cannot validate files.',
+      );
+      // ALLOW all files if no watch dirs configured (fail-safe)
+      return files;
+    }
+
+    // Normalize all watched directories for comparison
+    const normalizedWatchedDirs = watchedDirs.map((dir) => path.resolve(dir));
+
+    // Filter files that are within watched directories
+    const validatedFiles = files.filter((file) => {
+      const normalizedFilePath = path.resolve(file.path);
+
+      const isWatched = normalizedWatchedDirs.some((watchDir) => {
+        return (
+          normalizedFilePath.startsWith(watchDir + path.sep) ||
+          normalizedFilePath.startsWith(watchDir)
+        );
+      });
+
+      if (!isWatched) {
+        logger.debug(`📍 File not in watched directories: ${file.path}`);
+      }
+
+      return isWatched;
+    });
+
+    // Log validation results
+    if (validatedFiles.length < files.length) {
+      logger.warn(
+        `⚠️  Only ${validatedFiles.length}/${files.length} files passed watcher validation`,
+      );
+    }
+
+    return validatedFiles;
+  }
+
+  /**
+   * Validate command options
+   * @private
+   * @param {Object} options - Options to validate
+   * @throws {Error} If validation fails
+   */
+  #validateOptions(options) {
+    // Options are validated during parsing
+  }
+
+  /**
+   * Format file size for display
+   * @private
+   * @param {number} bytes - Number of bytes
+   * @returns {string} Formatted file size
+   */
+  #formatFileSize(bytes) {
+    if (bytes === 0) return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
+  }
+
+  /**
+   * Parse directories from string or array
+   * @private
+   * @param {string|Array} directoriesStr - Directories string or array
+   * @returns {Array<Object>} Parsed directory configurations
+   */
+  #parseDirectories(directoriesStr) {
+    try {
+      const config = appConfig.getWatchConfig();
+      let directoriesArray = [];
+
+      // Priority 1: CLI option
+      if (directoriesStr) {
+        directoriesArray = directoriesStr
+          .split(',')
+          .map((dir) => dir.trim())
+          .filter((dir) => dir.length > 0)
+          .map((dir) => ({
+            path: dir,
+            folderStructure: 'default',
+          }));
+
+        return directoriesArray;
+      }
+
+      // Priority 2: Environment config with JSON format
+      if (
+        config.directoryConfigs &&
+        Object.keys(config.directoryConfigs).length > 0
+      ) {
+        directoriesArray = Object.entries(config.directoryConfigs).map(
+          ([dirPath, folderStructure]) => ({
+            path: dirPath,
+            folderStructure: folderStructure || 'default',
+          }),
+        );
+
+        return directoriesArray;
+      }
+
+      // Priority 3: Environment config with legacy format
+      if (config.directories && config.directories.length > 0) {
+        directoriesArray = config.directories.map((dir) => ({
+          path: dir,
+          folderStructure: 'default',
+        }));
+
+        return directoriesArray;
+      }
+
+      return [];
+    } catch (error) {
+      logger.debug(`Error parsing directories: ${error.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Parse watch-specific options
+   * @private
+   * @param {Object} options - Command options
+   * @returns {Object} Parsed watch options
+   */
+  #parseWatchOptions(options) {
+    const config = appConfig.getWatchConfig();
+
+    return {
+      strategy: options.strategy || config.strategy || 'batch',
+      debounceMs: parseInt(options.debounce) || config.debounceMs || 1000,
+      batchSize: parseInt(options.batchSize) || config.batchSize || 10,
+      usePolling:
+        options.poll !== undefined ? true : config.usePolling || false,
+      interval: parseInt(options.poll) || config.pollInterval || 100,
+      stabilityThreshold: config.stabilityThreshold || 300,
+      autoDetect: options.autoDetect || config.autoDetect || false,
+      autoOrganize: options.autoOrganize || config.autoOrganize || false,
+    };
+  }
+
+  /**
+   * Parse ignore patterns from CLI
+   * @private
+   * @param {string|undefined} ignoreStr - Comma-separated patterns
+   * @returns {Array<string>} Ignore patterns
+   */
+  #parseIgnorePatterns(ignoreStr) {
+    const defaultPatterns = [
+      '/(^|[\\/\\\\])\\.|node_modules|\\.git/', // Hidden files, node_modules, .git
+    ];
+
+    if (!ignoreStr && !process.env.WATCH_IGNORE_PATTERNS) {
+      return defaultPatterns;
+    }
+
+    const patterns = (ignoreStr || process.env.WATCH_IGNORE_PATTERNS || '')
+      .split(',')
+      .map((p) => p.trim())
+      .filter((p) => p.length > 0);
+
+    return [...defaultPatterns, ...patterns];
+  }
+
+  /**
+   * Setup signal handlers for graceful shutdown
+   * @private
+   */
+  #setupSignalHandlers() {
+    // Register database cleanup
+    cleanupManager.registerResource('Database', databaseService, async () => {
+      return await databaseService.cleanup();
+    });
+
+    // Register watch service cleanup
+    cleanupManager.registerResource('WatchService', watchService, async () => {
+      return await watchService.stop('signal-received');
+    });
+
+    // Register logging flush
+    cleanupManager.registerResource('Logging', logger, () => {
+      logger.flush();
+    });
+
+    // Register progress bars cleanup
+    cleanupManager.registerResource('ProgressBars', this.progressBars, () => {
+      this.#stopProgressBars();
+    });
+
+    // Create signal handlers
+    const signalHandlers = {
+      SIGINT: async () => {
+        await this.#onShutdown('SIGINT');
+      },
+      SIGTERM: async () => {
+        await this.#onShutdown('SIGTERM');
+      },
+      SIGHUP: async () => {
+        await this.#onShutdown('SIGHUP');
+      },
+      SIGQUIT: async () => {
+        await this.#onShutdown('SIGQUIT');
+      },
+    };
+
+    // Register with signal handler
+    this.signalHandler.registerSignalHandlers(signalHandlers);
+
+    logger.debug('WatchCommand: Signal handlers configured');
+  }
+
+  /**
+   * Handle graceful shutdown triggered by signal
+   * @private
+   * @param {string} signal - Signal name that triggered shutdown
+   * @returns {Promise<void>}
+   */
+  async #onShutdown(signal) {
+    try {
+      // Print final statistics
+      const stats = watchService.getStats();
+      logger.info('\n═══════════════════════════════════════════════════════');
+      logger.info('📊 WATCH SESSION SUMMARY');
+      logger.info('═══════════════════════════════════════════════════════');
+      logger.info(`📄 Files added: ${stats.filesAdded}`);
+      logger.info(`✏️ Files modified: ${stats.filesModified}`);
+      logger.info(`🗑️ Files removed: ${stats.filesRemoved}`);
+      logger.info(`📤 Uploads triggered: ${stats.uploadsTriggered}`);
+      logger.info(`⚠️ Errors encountered: ${stats.errorsEncountered}`);
+      logger.info('═══════════════════════════════════════════════════════\n');
+
+      // Generate and display final session report
+      await this.#generateAndDisplaySessionReport(this.sessionId);
+    } catch (error) {
+      logger.error(`Error during shutdown handling: ${error.message}`);
+    }
+  }
+
+  /**
+   * Keep process alive indefinitely
+   * @private
+   * @returns {Promise<void>}
+   */
+  #keepProcessAlive() {
+    return new Promise(() => {
+      // Never resolves - process will run until signal is received
+    });
+  }
+
+  /**
+   * Initialize progress bars for upload tracking
+   * @private
+   * @returns {void}
+   */
+  #initializeProgressBars() {
+    this.progressBars = new cliProgress.MultiBar({
+      clearOnComplete: false,
+      hideCursor: true,
+      fps: 5,
+      stopOnComplete: false,
+      format:
+        '{name} | {bar} | {percentage}% | {value}/{total} | ⏱️  ETA: {eta_formatted} | 🚀 {speed}',
+      barCompleteChar: '█',
+      barIncompleteChar: '░',
+      hideCursor: true,
+      formatBar: (processed, total, width) => {
+        const ratio = processed / total;
+        const filled = Math.round(ratio * width);
+        const empty = width - filled;
+        return '█'.repeat(filled) + '░'.repeat(empty);
+      },
+    });
+
+    // Create bars for each strategy
+    this.progressBars.individual = this.progressBars.create(0, 0, {
+      name: '📁 Individual',
+      speed: '0 files/min',
+    });
+
+    this.progressBars.batch = this.progressBars.create(0, 0, {
+      name: '📦 Batch     ',
+      speed: '0 files/min',
+    });
+
+    this.progressBars['full-structure'] = this.progressBars.create(0, 0, {
+      name: '🗂️  Full-Str ',
+      speed: '0 files/min',
+    });
+
+    // Initialize metrics
+    this.progressMetrics = {
+      individual: { start: null, processed: 0, total: 0 },
+      batch: { start: null, processed: 0, total: 0 },
+      'full-structure': { start: null, processed: 0, total: 0 },
+    };
+  }
+
+  /**
+   * Update progress bar for a specific strategy
+   * @private
+   * @param {string} strategy - Upload strategy name
+   * @param {number} processed - Number of processed files
+   * @param {number} total - Total number of files
+   * @returns {void}
+   */
+  #updateProgressBar(strategy, processed, total) {
+    if (!this.progressBars || !this.progressBars[strategy]) {
+      return;
+    }
+
+    const metrics = this.progressMetrics[strategy];
+
+    // Initialize start time if not already done
+    if (metrics.start === null) {
+      metrics.start = Date.now();
+    }
+
+    metrics.processed = processed;
+    metrics.total = total;
+
+    // Calculate speed (files per minute)
+    const elapsedMs = Date.now() - metrics.start;
+    const elapsedMin = elapsedMs / 60000;
+    const speed = elapsedMin > 0 ? (processed / elapsedMin).toFixed(1) : '0';
+
+    // Update bar
+    this.progressBars[strategy].setTotal(total);
+    this.progressBars[strategy].update(processed, {
+      speed: `${speed} files/min`,
+    });
+  }
+
+  /**
+   * Complete a progress bar for a strategy
+   * @private
+   * @param {string} strategy - Upload strategy name
+   * @param {Object} results - Upload results (successCount, failureCount, duration)
+   * @returns {void}
+   */
+  #completeProgressBar(strategy, results) {
+    if (!this.progressBars || !this.progressBars[strategy]) {
+      return;
+    }
+
+    const metrics = this.progressMetrics[strategy];
+    const bar = this.progressBars[strategy];
+    const total = results.fileCount || metrics.total;
+    const duration = results.duration || 0;
+
+    // Calculate final speed
+    const durationSec = duration / 1000;
+    const speed =
+      durationSec > 0 ? (total / (durationSec / 60)).toFixed(1) : '0';
+
+    // Set to complete
+    bar.setTotal(total);
+    bar.update(total, {
+      speed: `${speed} files/min`,
+    });
+  }
+
+  /**
+   * Calculate ETA (Estimated Time to Arrival)
+   * @private
+   * @param {number} startTime - Start timestamp
+   * @param {number} processed - Number of processed items
+   * @param {number} total - Total number of items
+   * @returns {string} Formatted ETA string
+   */
+  #calculateETA(startTime, processed, total) {
+    if (processed === 0 || total === 0) {
+      return '--:--:--';
+    }
+
+    const elapsedMs = Date.now() - startTime;
+    const avgTimePerItem = elapsedMs / processed;
+    const remainingItems = total - processed;
+    const remainingMs = remainingItems * avgTimePerItem;
+
+    const hours = Math.floor(remainingMs / 3600000);
+    const minutes = Math.floor((remainingMs % 3600000) / 60000);
+    const seconds = Math.floor((remainingMs % 60000) / 1000);
+
+    if (hours > 0) {
+      return `${hours}h ${minutes}m`;
+    } else if (minutes > 0) {
+      return `${minutes}m ${seconds}s`;
+    } else {
+      return `${seconds}s`;
+    }
+  }
+
+  /**
+   * Stop and cleanup progress bars
+   * @private
+   * @returns {void}
+   */
+  #stopProgressBars() {
+    if (this.progressBars) {
+      try {
+        this.progressBars.stop();
+      } catch (error) {
+        logger.debug(`Error stopping progress bars: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Generate and display final session report
+   * @private
+   * @param {string} sessionId - Session ID to generate report for
+   * @returns {Promise<void>}
+   */
+  async #generateAndDisplaySessionReport(sessionId) {
+    try {
+      // Get final statistics from DatabaseService
+      const stats = await databaseService.getSessionStatistics(sessionId);
+
+      // Generate formatted report
+      const report = logger.formatSessionReport();
+
+      // Display report in console
+      console.log(report);
+
+      // Save report to file
+      await this.#saveReportToFile(sessionId, report);
+
+      logger.info(
+        `Session report generated successfully for session: ${sessionId}`,
+      );
+    } catch (error) {
+      logger.error(`Error generating session report: ${error.message}`);
+    }
+  }
+
+  /**
+   * Save session report to file
+   * @private
+   * @param {string} sessionId - Session ID
+   * @param {string} report - Report content to save
+   * @returns {Promise<void>}
+   */
+  async #saveReportToFile(sessionId, report) {
+    try {
+      const logDir = path.join(process.cwd(), 'logs', 'sessions');
+      const timestamp = Date.now();
+      const fileName = `session-${sessionId}-${timestamp}.log`;
+      const filePath = path.join(logDir, fileName);
+
+      // Create directory if it doesn't exist
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+
+      // Write report to file
+      fs.writeFileSync(filePath, report, 'utf-8');
+
+      logger.info(`Session report saved to: ${filePath}`);
+    } catch (error) {
+      logger.error(`Error saving report to file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Generate intelligent recommendations based on session statistics
+   * @private
+   * @param {Object} stats - Session statistics object
+   * @returns {string} Formatted recommendations
+   */
+  #generateRecommendations(stats) {
+    const recommendations = [];
+
+    // Analyze success rate
+    const successRate =
+      (stats.totalSuccessCount /
+        (stats.totalSuccessCount + stats.totalFailureCount)) *
+      100;
+    if (successRate >= 95) {
+      recommendations.push(
+        '✅ Excellent performance! Success rate is outstanding.',
+      );
+    } else if (successRate >= 80) {
+      recommendations.push(
+        '⚠️ Good performance, but there is room for improvement.',
+      );
+    } else {
+      recommendations.push('❌ Poor performance. Check logs for issues.');
+    }
+
+    // Analyze retries
+    if (stats.retryStats.totalRetries === 0) {
+      recommendations.push(
+        '✅ No retries needed - upload system is very stable.',
+      );
+    } else if (stats.retryStats.totalRetries <= 5) {
+      recommendations.push('ℹ️ Low retry count - system is fairly stable.');
+    } else {
+      recommendations.push(
+        '⚠️ High retry count - consider optimizing upload settings.',
+      );
+    }
+
+    // Analyze strategies
+    const byStrategy = stats.byStrategy;
+    const strategies = Object.entries(byStrategy)
+      .filter(([_, s]) => s.uploadCount > 0)
+      .sort((a, b) => {
+        const aSpeed =
+          a[1].totalDuration > 0
+            ? a[1].totalFiles / (a[1].totalDuration / 60000)
+            : 0;
+        const bSpeed =
+          b[1].totalDuration > 0
+            ? b[1].totalFiles / (b[1].totalDuration / 60000)
+            : 0;
+        return bSpeed - aSpeed;
+      });
+
+    if (strategies.length > 0) {
+      const fastest = strategies[0];
+      const speed = (
+        fastest[1].totalFiles /
+        (fastest[1].totalDuration / 60000)
+      ).toFixed(1);
+      recommendations.push(
+        `💡 Most efficient strategy: ${fastest[0]} (${speed} files/min)`,
+      );
+    }
+
+    // Format recommendations for display
+    let result = '';
+    recommendations.forEach((rec, idx) => {
+      result += `│ ${rec}\n`;
+    });
+
+    return result;
+  }
+}
+
+// Export singleton instance
+export default new WatchCommand();