@arela/uploader 1.1.3 → 1.2.0

package/.claude/worktrees/agent-multi-profile/src/config/config.js

@@ -0,0 +1,862 @@
+import { config } from 'dotenv';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import PathNormalizer from '../utils/PathNormalizer.js';
+
+config();
+
+/**
+ * Configuration management for Arela Uploader
+ * Centralizes all environment variable handling and validation
+ */
+class Config {
+  constructor() {
+    this.packageVersion = this.#loadPackageVersion();
+    this.supabase = this.#loadSupabaseConfig();
+    this.api = this.#loadApiConfig();
+    this.upload = this.#loadUploadConfig();
+    this.scan = this.#loadScanConfig();
+    this.push = this.#loadPushConfig();
+    this.performance = this.#loadPerformanceConfig();
+    this.logging = this.#loadLoggingConfig();
+    this.watch = this.#loadWatchConfig();
+    this.redis = this.#loadRedisConfig();
+    this.worker = this.#loadWorkerConfig();
+    this.gdrive = this.#loadGDriveConfig();
+  }
+
+  /**
+   * Load package version from package.json
+   * @private
+   */
+  #loadPackageVersion() {
+    try {
+      const __filename = fileURLToPath(import.meta.url);
+      const __dirname = path.dirname(__filename);
+      const packageJsonPath = path.resolve(__dirname, '../../package.json');
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      return packageJson.version || '1.2.0';
+    } catch (error) {
+      console.warn('⚠️ Could not read package.json version, using fallback');
+      return '1.2.0';
+    }
+  }
+
+  /**
+   * Load Supabase configuration
+   * @private
+   */
+  #loadSupabaseConfig() {
+    return {
+      url: process.env.SUPABASE_URL,
+      key: process.env.SUPABASE_KEY,
+      bucket: process.env.SUPABASE_BUCKET,
+    };
+  }
+
+  /**
+   * Load API configuration
+   * Supports 3 API targets: default, agencia, cliente
+   * Configure ARELA_API_CLIENTE_URL/TOKEN for the specific client you want to use
+   * @private
+   */
+  #loadApiConfig() {
+    return {
+      // Default/legacy API (backward compatible)
+      baseUrl: process.env.ARELA_API_URL,
+      token: process.env.ARELA_API_TOKEN,
+      // Multi-tenant API targets (only 3 options)
+      targets: {
+        agencia: {
+          baseUrl:
+            process.env.ARELA_API_AGENCIA_URL || process.env.ARELA_API_URL,
+          token:
+            process.env.ARELA_API_AGENCIA_TOKEN || process.env.ARELA_API_TOKEN,
+        },
+        cliente: {
+          baseUrl:
+            process.env.ARELA_API_CLIENTE_URL || process.env.ARELA_API_URL,
+          token:
+            process.env.ARELA_API_CLIENTE_TOKEN || process.env.ARELA_API_TOKEN,
+        },
+        // Dynamic targets - add more as needed via ARELA_API_{NAME}_URL
+        ktj: {
+          baseUrl: process.env.ARELA_API_KTJ_URL || process.env.ARELA_API_URL,
+          token: process.env.ARELA_API_KTJ_TOKEN || process.env.ARELA_API_TOKEN,
+        },
+      },
+      // Current active target (can be changed at runtime)
+      activeTarget: process.env.ARELA_API_TARGET || 'default',
+    };
+  }
+
+  /**
+   * Get API configuration for a specific target
+   * @param {string} target - API target: 'agencia', 'cliente', or 'default'
+   * @returns {Object} API configuration with baseUrl and token
+   */
+  getApiConfig(target = null) {
+    const targetName = target || this.api.activeTarget || 'default';
+
+    if (targetName === 'default') {
+      return {
+        baseUrl: this.api.baseUrl,
+        token: this.api.token,
+      };
+    }
+
+    const targetConfig = this.api.targets[targetName];
+    if (!targetConfig) {
+      console.warn(
+        `⚠️ Unknown API target '${targetName}', falling back to default`,
+      );
+      return {
+        baseUrl: this.api.baseUrl,
+        token: this.api.token,
+      };
+    }
+
+    return targetConfig;
+  }
+
+  /**
+   * Set the active API target at runtime
+   * @param {string} target - API target: 'default', 'agencia', or 'cliente'
+   */
+  setApiTarget(target) {
+    const validTargets = ['default', ...Object.keys(this.api.targets)];
+    if (!validTargets.includes(target.toLowerCase())) {
+      throw new Error(
+        `Invalid API target '${target}'. Must be one of: ${validTargets.join(', ')}`,
+      );
+    }
+    this.api.activeTarget = target.toLowerCase();
+    const config = this.getApiConfig(target.toLowerCase());
+    console.log(`🎯 API target set to: ${target} → ${config.baseUrl}`);
+  }
+
+  /**
+   * Set source and target APIs for cross-tenant operations
+   * @param {string} sourceTarget - Source API target (for reading data)
+   * @param {string} targetTarget - Target API target (for writing data)
+   */
+  setCrossTenantTargets(sourceTarget, targetTarget) {
+    const validTargets = ['default', ...Object.keys(this.api.targets)];
+
+    if (!validTargets.includes(sourceTarget.toLowerCase())) {
+      throw new Error(
+        `Invalid source API target '${sourceTarget}'. Must be one of: ${validTargets.join(', ')}`,
+      );
+    }
+    if (!validTargets.includes(targetTarget.toLowerCase())) {
+      throw new Error(
+        `Invalid target API target '${targetTarget}'. Must be one of: ${validTargets.join(', ')}`,
+      );
+    }
+
+    this.api.sourceTarget = sourceTarget.toLowerCase();
+    this.api.targetTarget = targetTarget.toLowerCase();
+
+    const sourceConfig = this.getApiConfig(sourceTarget.toLowerCase());
+    const targetConfig = this.getApiConfig(targetTarget.toLowerCase());
+
+    console.log(`🔗 Cross-tenant mode enabled:`);
+    console.log(
+      `   📖 Source (read): ${sourceTarget} → ${sourceConfig.baseUrl}`,
+    );
+    console.log(
+      `   📝 Target (write): ${targetTarget} → ${targetConfig.baseUrl}`,
+    );
+  }
+
+  /**
+   * Upsert an API target in memory (does not touch process.env).
+   * Used by agent mode to register per-profile targets at runtime.
+   * @param {string} name - Target name, e.g. 'cliente', 'agencia'
+   * @param {{baseUrl: string, token: string}} targetConfig
+   */
+  setTargetConfig(name, { baseUrl, token }) {
+    this.api.targets[name.toLowerCase()] = { baseUrl, token };
+  }
+
+  /**
+   * Apply an agent profile: API targets, server id and env overrides.
+   * Idempotent — the agent calls it before every poll/job of the profile so the
+   * singleton always reflects the ACTIVE profile (jobs reference targets by
+   * symbolic name: 'agencia', 'cliente').
+   * @param {Object} profile - Normalized profile from ProfileManager
+   */
+  applyProfile(profile) {
+    this.api.baseUrl = profile.url;
+    this.api.token = profile.token;
+    for (const [name, targetConfig] of Object.entries(profile.targets)) {
+      this.setTargetConfig(name, targetConfig);
+    }
+    if (profile.serverId) {
+      process.env.ARELA_SERVER_ID = profile.serverId;
+    }
+    for (const [key, value] of Object.entries(profile.env || {})) {
+      process.env[key] = String(value);
+    }
+    // Clear cross-tenant state left over from a previous profile's job
+    this.api.sourceTarget = null;
+    this.api.targetTarget = null;
+    this.api.activeTarget = 'default';
+  }
+
+  /**
+   * Get source API config for cross-tenant operations
+   * @returns {Object} Source API configuration
+   */
+  getSourceApiConfig() {
+    if (this.api.sourceTarget) {
+      return this.getApiConfig(this.api.sourceTarget);
+    }
+    return this.getApiConfig();
+  }
+
+  /**
+   * Get target API config for cross-tenant operations
+   * @returns {Object} Target API configuration
+   */
+  getTargetApiConfig() {
+    if (this.api.targetTarget) {
+      return this.getApiConfig(this.api.targetTarget);
+    }
+    return this.getApiConfig();
+  }
+
+  /**
+   * Check if cross-tenant mode is enabled
+   * @returns {boolean}
+   */
+  isCrossTenantMode() {
+    return !!(
+      this.api.sourceTarget &&
+      this.api.targetTarget &&
+      this.api.sourceTarget !== this.api.targetTarget
+    );
+  }
+
+  /**
+   * Get API target by RFC
+   * @param {string} rfc - The RFC to find API target for
+   * @returns {string|null} The API target name or null if not found
+   */
+  getApiTargetByRfc(rfc) {
+    if (!rfc) return null;
+
+    const normalizedRfc = rfc.toUpperCase();
+    for (const [targetName, targetConfig] of Object.entries(this.api.targets)) {
+      if (
+        targetConfig.rfc &&
+        targetConfig.rfc.toUpperCase() === normalizedRfc
+      ) {
+        return targetName;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Load upload configuration
+   * @private
+   */
+  #loadUploadConfig() {
+    const basePath = process.env.UPLOAD_BASE_PATH;
+    const sources = process.env.UPLOAD_SOURCES?.split('|')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    const uploadRfcs = process.env.UPLOAD_RFCS?.split('|')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    const uploadYears = process.env.UPLOAD_YEARS?.split('|')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    return {
+      basePath,
+      sources,
+      rfcs: uploadRfcs,
+      years: uploadYears,
+    };
+  }
+
+  /**
+   * Load scan configuration
+   * @private
+   */
+  #loadScanConfig() {
+    const companySlug = process.env.ARELA_COMPANY_SLUG;
+    const serverId = process.env.ARELA_SERVER_ID;
+    let basePathLabel = process.env.ARELA_BASE_PATH_LABEL;
+
+    // Auto-derive basePathLabel from UPLOAD_BASE_PATH if not set
+    // IMPORTANT: Always resolve to absolute path for uniqueness
+    if (!basePathLabel && process.env.UPLOAD_BASE_PATH) {
+      const basePath = process.env.UPLOAD_BASE_PATH;
+      // '*' is a wildcard sentinel for cross-drive scenarios — keep as-is
+      if (basePath === '*') {
+        basePathLabel = '*';
+      } else {
+        // Resolve to absolute path (handles ../sample vs ./sample correctly)
+        // Note: toAbsolutePath handles Windows paths (O:\...) even on macOS/Linux
+        basePathLabel = PathNormalizer.toAbsolutePath(basePath);
+      }
+    }
+
+    // If basePathLabel is provided, ensure it's absolute (skip wildcard)
+    // Use PathNormalizer.isAbsolutePath for cross-platform Windows path detection
+    if (
+      basePathLabel &&
+      basePathLabel !== '*' &&
+      !PathNormalizer.isAbsolutePath(basePathLabel)
+    ) {
+      basePathLabel = PathNormalizer.toAbsolutePath(basePathLabel);
+    }
+
+    // Parse exclude patterns
+    const defaultExcludePatterns =
+      '.DS_Store,Thumbs.db,desktop.ini,__pycache__,.pyc,.tmp,.swp,$RECYCLE.BIN,System Volume Information,~$*';
+    const excludePatterns = (
+      process.env.SCAN_EXCLUDE_PATTERNS || defaultExcludePatterns
+    )
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean);
+
+    // Parse inter-agency CFDI filename patterns. Files whose basename matches
+    // any of these regex patterns are flagged at scan time (likelyInterAgencia)
+    // so the API forces them through detection and the factura_inter_agencia
+    // matcher can classify them. The push pipeline then excludes them (see
+    // NON_PUSHABLE_TYPES_SQL in arela-api). Comma-separated regex source list.
+    // Default: ^SICINGR — covers NORCOM's SICINGR70-NNNNNN(...).pdf/.XML files.
+    const defaultInterAgenciaPatterns = '^SICINGR';
+    const interAgenciaPatterns = (
+      process.env.SCAN_INTER_AGENCIA_PATTERNS || defaultInterAgenciaPatterns
+    )
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean)
+      .map((p) => {
+        try {
+          return new RegExp(p, 'i');
+        } catch (err) {
+          console.warn(
+            `⚠️ Invalid SCAN_INTER_AGENCIA_PATTERNS regex "${p}": ${err.message}`,
+          );
+          return null;
+        }
+      })
+      .filter(Boolean);
+
+    // Generate table name if all components are available
+    // Note: This is just for reference; actual table names are generated dynamically
+    // in ScanCommand based on discovered directories and levels
+    let tableName = null;
+    if (companySlug && serverId && basePathLabel && basePathLabel !== '*') {
+      tableName = PathNormalizer.generateTableName({
+        companySlug,
+        serverId,
+        basePathLabel,
+      });
+    }
+
+    return {
+      companySlug,
+      serverId,
+      basePathFull: basePathLabel, // Renamed for consistency
+      tableName,
+      excludePatterns,
+      interAgenciaPatterns,
+      batchSize: parseInt(process.env.SCAN_BATCH_SIZE) || 2000,
+      directoryLevel: parseInt(process.env.SCAN_DIRECTORY_LEVEL) || 0,
+    };
+  }
+
+  /**
+   * Load push configuration
+   * @private
+   */
+  #loadPushConfig() {
+    const pushRfcs = process.env.PUSH_RFCS?.split('|')
+      .map((s) => s.trim().toUpperCase())
+      .filter(Boolean);
+
+    const pushYears = process.env.PUSH_YEARS?.split('|')
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((y) => !isNaN(y));
+
+    // Clean folder structure: remove leading/trailing slashes
+    const folderStructure = process.env.PUSH_FOLDER_STRUCTURE?.trim()
+      .replace(/^\/+/, '')
+      .replace(/\/+$/, '');
+
+    return {
+      rfcs: pushRfcs,
+      years: pushYears,
+      batchSize: parseInt(process.env.PUSH_BATCH_SIZE) || 50,
+      uploadBatchSize: parseInt(process.env.PUSH_UPLOAD_BATCH_SIZE) || 10,
+      bucket:
+        process.env.PUSH_BUCKET || process.env.SUPABASE_BUCKET || 'archivos',
+      folderStructure: folderStructure || '', // Prefix for storage path (e.g., "documents" or "uploads/2024")
+    };
+  }
+
+  /**
+   * Validate scan configuration
+   * @throws {Error} If required scan configuration is missing
+   */
+  validateScanConfig() {
+    const errors = [];
+
+    if (!this.scan.companySlug) {
+      errors.push(
+        'ARELA_COMPANY_SLUG is required (e.g., "acme_corp", "cliente_123")',
+      );
+    } else if (!/^[a-zA-Z0-9_-]+$/.test(this.scan.companySlug)) {
+      errors.push(
+        'ARELA_COMPANY_SLUG must contain only alphanumeric characters, dashes, and underscores',
+      );
+    }
+
+    if (!this.scan.serverId) {
+      errors.push(
+        'ARELA_SERVER_ID is required (e.g., "nas01", "server-mx", "storage-01")',
+      );
+    } else if (!/^[a-zA-Z0-9_-]+$/.test(this.scan.serverId)) {
+      errors.push(
+        'ARELA_SERVER_ID must contain only alphanumeric characters, dashes, and underscores',
+      );
+    }
+
+    if (!this.upload.basePath) {
+      errors.push(
+        'UPLOAD_BASE_PATH is required to determine the scan base path',
+      );
+    }
+
+    if (!this.scan.basePathFull) {
+      errors.push(
+        'Could not determine base path. Set ARELA_BASE_PATH_LABEL or UPLOAD_BASE_PATH',
+      );
+    }
+
+    if (errors.length > 0) {
+      throw new Error(
+        '⚠️ Scan configuration errors:\n   - ' + errors.join('\n   - '),
+      );
+    }
+  }
+
+  /**
+   * Get scan configuration
+   * @returns {Object} Scan configuration
+   */
+  getScanConfig() {
+    // Return scan config with basePathFull already resolved to absolute path
+    return this.scan;
+  }
+
+  /**
+   * Get push configuration
+   * @returns {Object} Push configuration
+   */
+  getPushConfig() {
+    return {
+      ...this.push,
+      rfcs: this.push.rfcs || [],
+      years: this.push.years || [],
+    };
+  }
+
+  /**
+   * Load performance configuration
+   * @private
+   */
+  #loadPerformanceConfig() {
+    return {
+      batchDelay: parseInt(process.env.BATCH_DELAY) || 0, // Removed default delay
+      batchSize: parseInt(process.env.BATCH_SIZE) || 50, // Increased from 10 to 50
+      maxConcurrentSources: parseInt(process.env.MAX_CONCURRENT_SOURCES) || 2,
+      maxApiConnections: parseInt(process.env.MAX_API_CONNECTIONS) || 10, // New: API replica support
+      apiConnectionTimeout:
+        parseInt(process.env.API_CONNECTION_TIMEOUT) || 60000, // New: API timeout
+      progressUpdateInterval:
+        parseInt(process.env.PROGRESS_UPDATE_INTERVAL) || 10,
+      logBufferSize: 100,
+      logFlushInterval: 5000,
+    };
+  }
+
+  /**
+   * Load logging configuration
+   * @private
+   */
+  #loadLoggingConfig() {
+    return {
+      verbose: process.env.VERBOSE_LOGGING === 'true',
+      logFilePath: path.resolve(process.cwd(), 'arela-upload.log'),
+    };
+  }
+
+  /**
+   * Load watch configuration
+   * @private
+   */
+  #loadWatchConfig() {
+    // Parse directory configs from JSON format
+    let directoryConfigs = {};
+    if (process.env.WATCH_DIRECTORY_CONFIGS) {
+      try {
+        directoryConfigs = JSON.parse(process.env.WATCH_DIRECTORY_CONFIGS);
+      } catch (error) {
+        console.warn(
+          '⚠️ Invalid JSON in WATCH_DIRECTORY_CONFIGS, using empty config',
+        );
+        directoryConfigs = {};
+      }
+    }
+
+    // Fallback to WATCH_DIRECTORIES for backward compatibility
+    let directories = [];
+    if (
+      Object.keys(directoryConfigs).length === 0 &&
+      process.env.WATCH_DIRECTORIES
+    ) {
+      directories = process.env.WATCH_DIRECTORIES.split(',')
+        .map((d) => d.trim())
+        .filter(Boolean);
+    }
+
+    // Parse ignore patterns
+    const ignorePatterns =
+      process.env.WATCH_IGNORE_PATTERNS?.split(',')
+        .map((p) => p.trim())
+        .filter(Boolean) || [];
+
+    return {
+      enabled: process.env.WATCH_ENABLED === 'true' || false,
+      directories,
+      directoryConfigs,
+      strategy: process.env.WATCH_STRATEGY || 'batch',
+      debounceMs: parseInt(process.env.WATCH_DEBOUNCE_MS) || 1000,
+      batchSize: parseInt(process.env.WATCH_BATCH_SIZE) || 10,
+      usePolling: process.env.WATCH_USE_POLLING === 'true' || false,
+      pollInterval: parseInt(process.env.WATCH_POLL_INTERVAL) || 100,
+      stabilityThreshold:
+        parseInt(process.env.WATCH_STABILITY_THRESHOLD) || 300,
+      ignorePatterns,
+      autoDetect: process.env.WATCH_AUTO_DETECT === 'true' || false,
+      autoOrganize: process.env.WATCH_AUTO_ORGANIZE === 'true' || false,
+    };
+  }
+
+  /**
+   * Check if API mode is available
+   * @param {string} target - Optional API target to check
+   * @returns {boolean}
+   */
+  isApiModeAvailable(target = null) {
+    const config = this.getApiConfig(target);
+    return !!(config.baseUrl && config.token);
+  }
+
+  /**
+   * Check if Supabase mode is available
+   * @returns {boolean}
+   */
+  isSupabaseModeAvailable() {
+    return !!(this.supabase.url && this.supabase.key && this.supabase.bucket);
+  }
+
+  /**
+   * Load Redis configuration for BullMQ worker mode
+   * @private
+   */
+  #loadRedisConfig() {
+    return {
+      host: process.env.REDIS_HOST || 'localhost',
+      port: parseInt(process.env.REDIS_PORT) || 6379,
+      password: process.env.REDIS_PASSWORD || undefined,
+      db: parseInt(process.env.REDIS_DB) || 0,
+      maxRetriesPerRequest: null, // Required by BullMQ
+    };
+  }
+
+  /**
+   * Load worker configuration
+   * @private
+   */
+  #loadWorkerConfig() {
+    const queues = process.env.WORKER_QUEUES?.split(',')
+      .map((q) => q.trim())
+      .filter(Boolean) || [
+      'pipeline-scan',
+      'pipeline-identify',
+      'pipeline-propagate',
+      'pipeline-push',
+    ];
+
+    return {
+      queues,
+      concurrency: parseInt(process.env.WORKER_CONCURRENCY) || 1,
+      lockDuration: parseInt(process.env.WORKER_LOCK_DURATION) || 30000,
+      stalledInterval: parseInt(process.env.WORKER_STALLED_INTERVAL) || 30000,
+      // HTTP Polling mode configuration
+      poll: {
+        enabled: process.env.WORKER_POLL_MODE === 'true',
+        interval: parseInt(process.env.WORKER_POLL_INTERVAL) || 5000,
+        apiTarget: process.env.WORKER_POLL_API_TARGET || 'agencia',
+      },
+    };
+  }
+
+  /**
+   * Get Redis configuration
+   * @returns {Object} Redis connection options for ioredis/BullMQ
+   */
+  getRedisConfig() {
+    return this.redis;
+  }
+
+  /**
+   * Get worker configuration
+   * @returns {Object} Worker settings
+   */
+  getWorkerConfig() {
+    return this.worker;
+  }
+
+  /**
+   * Get the server ID for this instance
+   * Used for worker job assignment in poll mode
+   * @returns {string|null} Server ID or null if not configured
+   */
+  getServerId() {
+    return process.env.ARELA_SERVER_ID || null;
+  }
+
+  /**
+   * Load Google Drive sync configuration
+   * @private
+   */
+  #loadGDriveConfig() {
+    const rootFolderId = process.env.GDRIVE_ROOT_FOLDER_ID || null;
+
+    // Default mirror destination: <UPLOAD_BASE_PATH>/_gdrive_mirror
+    let localMirrorPath = process.env.GDRIVE_LOCAL_MIRROR_PATH || null;
+    if (!localMirrorPath && process.env.UPLOAD_BASE_PATH) {
+      const base = process.env.UPLOAD_BASE_PATH;
+      if (base !== '*') {
+        localMirrorPath = path.resolve(
+          PathNormalizer.toAbsolutePath(base),
+          '_gdrive_mirror',
+        );
+      }
+    } else if (localMirrorPath) {
+      localMirrorPath = PathNormalizer.toAbsolutePath(localMirrorPath);
+    }
+
+    return {
+      rootFolderId,
+      localMirrorPath,
+      serviceAccountFile: process.env.GDRIVE_SERVICE_ACCOUNT_FILE || null,
+      serviceAccountJson: process.env.GDRIVE_SERVICE_ACCOUNT_JSON || null,
+      skipNativeDocs: process.env.GDRIVE_SKIP_NATIVE_DOCS !== 'false',
+      followShortcuts: process.env.GDRIVE_FOLLOW_SHORTCUTS !== 'false',
+      concurrency: parseInt(process.env.GDRIVE_CONCURRENCY) || 5,
+      pageSize: parseInt(process.env.GDRIVE_PAGE_SIZE) || 1000,
+      maxFileSizeBytes:
+        parseInt(process.env.GDRIVE_MAX_FILE_SIZE_BYTES) ||
+        2 * 1024 * 1024 * 1024, // 2GB default
+    };
+  }
+
+  /**
+   * Get Google Drive configuration
+   * @returns {Object} GDrive sync settings
+   */
+  getGDriveConfig() {
+    return this.gdrive;
+  }
+
+  /**
+   * Validate Google Drive configuration
+   * @throws {Error} If required gdrive configuration is missing
+   */
+  validateGDriveConfig() {
+    const errors = [];
+
+    if (!this.gdrive.rootFolderId) {
+      errors.push(
+        'GDRIVE_ROOT_FOLDER_ID is required (Drive folder ID to sync)',
+      );
+    }
+
+    if (!this.gdrive.localMirrorPath) {
+      errors.push(
+        'Could not determine local mirror path. Set GDRIVE_LOCAL_MIRROR_PATH or UPLOAD_BASE_PATH',
+      );
+    }
+
+    if (!this.gdrive.serviceAccountFile && !this.gdrive.serviceAccountJson) {
+      errors.push(
+        'Either GDRIVE_SERVICE_ACCOUNT_FILE (path to JSON) or GDRIVE_SERVICE_ACCOUNT_JSON (inline JSON) is required',
+      );
+    }
+
+    if (this.gdrive.serviceAccountFile) {
+      const resolved = PathNormalizer.toAbsolutePath(
+        this.gdrive.serviceAccountFile,
+      );
+      if (!fs.existsSync(resolved)) {
+        errors.push(`GDRIVE_SERVICE_ACCOUNT_FILE not found: ${resolved}`);
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new Error(
+        '⚠️ Google Drive configuration errors:\n   - ' + errors.join('\n   - '),
+      );
+    }
+  }
+
+  /**
+   * Check if worker mode is available (Redis configured)
+   * @returns {boolean}
+   */
+  isWorkerModeAvailable() {
+    return !!(this.redis.host && this.redis.port);
+  }
+
+  /**
+   * Validate configuration for the requested mode
+   * @param {boolean} forceSupabase - Whether to force Supabase mode
+   * @throws {Error} If required configuration is missing
+   */
+  validateConfiguration(forceSupabase = false) {
+    if (forceSupabase) {
+      if (!this.isSupabaseModeAvailable()) {
+        throw new Error(
+          '⚠️ Missing Supabase credentials. Please set SUPABASE_URL, SUPABASE_KEY, and SUPABASE_BUCKET',
+        );
+      }
+      return;
+    }
+
+    if (!this.isApiModeAvailable() && !this.isSupabaseModeAvailable()) {
+      throw new Error(
+        '⚠️ Missing credentials. Please set either:\n' +
+          '   - ARELA_API_URL and ARELA_API_TOKEN for API mode, or\n' +
+          '   - SUPABASE_URL, SUPABASE_KEY, and SUPABASE_BUCKET for direct mode',
+      );
+    }
+  }
+
+  /**
+   * Get upload sources with validation
+   * @returns {string[]} Array of upload sources (defaults to ['.'] if not configured)
+   */
+  getUploadSources() {
+    if (!this.upload.sources || this.upload.sources.length === 0) {
+      return ['.'];
+    }
+    return this.upload.sources;
+  }
+
+  /**
+   * Get base path with validation
+   * Returns the path as configured (may be relative for legacy compatibility)
+   * @returns {string} Base path for uploads
+   * @throws {Error} If base path is not configured
+   */
+  getBasePath() {
+    if (!this.upload.basePath) {
+      throw new Error(
+        '⚠️ No base path configured. Please set UPLOAD_BASE_PATH environment variable.',
+      );
+    }
+    return this.upload.basePath;
+  }
+
+  /**
+   * Get watch directories with validation
+   * @param {string[]} cliDirs - Directories from CLI options
+   * @returns {string[]} Validated watch directories
+   * @throws {Error} If no directories are configured
+   */
+  getWatchDirectories(cliDirs = null) {
+    // CLI options take precedence over environment variables
+    const directories =
+      cliDirs && cliDirs.length > 0 ? cliDirs : this.watch.directories;
+
+    if (!directories || directories.length === 0) {
+      throw new Error(
+        '⚠️ No watch directories configured. Please use --directories option or set WATCH_DIRECTORIES environment variable.',
+      );
+    }
+
+    return directories;
+  }
+
+  /**
+   * Get watch configuration with validation
+   * @returns {Object} Watch configuration object
+   */
+  getWatchConfig() {
+    return {
+      ...this.watch,
+    };
+  }
+
+  /**
+   * Reload upload, scan, push and performance config from current process.env
+   * values. Must be called after modifying env vars at runtime (e.g.,
+   * PipelineJobRunner applying a job's scanConfig/tuning overrides).
+   */
+  reloadScanConfig() {
+    this.upload = this.#loadUploadConfig();
+    this.scan = this.#loadScanConfig();
+    this.push = this.#loadPushConfig();
+    this.performance = this.#loadPerformanceConfig();
+  }
+
+  /**
+   * Validate watch configuration
+   * @param {string[]} directories - Directories to validate
+   * @throws {Error} If configuration is invalid
+   */
+  validateWatchConfig(directories) {
+    if (!directories || directories.length === 0) {
+      throw new Error(
+        'At least one directory must be specified for watch mode',
+      );
+    }
+
+    // Validate strategy
+    const validStrategies = ['individual', 'batch', 'full-structure'];
+    if (!validStrategies.includes(this.watch.strategy)) {
+      throw new Error(
+        `Invalid watch strategy: ${this.watch.strategy}. Must be one of: ${validStrategies.join(', ')}`,
+      );
+    }
+
+    // Validate debounce and batch size
+    if (this.watch.debounceMs < 0) {
+      throw new Error('Debounce time must be >= 0');
+    }
+
+    if (this.watch.batchSize < 1) {
+      throw new Error('Batch size must be >= 1');
+    }
+  }
+}
+
+// Export singleton instance
+export const appConfig = new Config();
+export default appConfig;