appwrite-utils-cli 1.9.7 → 1.11.0

package/dist/config/ConfigManager.js

@@ -1,650 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { ConfigDiscoveryService, ConfigLoaderService, ConfigMergeService, ConfigValidationService, SessionAuthService, } from "./services/index.js";
-import { MessageFormatter } from "../shared/messageFormatter.js";
-import { logger } from "../shared/logging.js";
-import { detectAppwriteVersionCached } from "../utils/versionDetection.js";
-/**
- * Centralized configuration manager with intelligent caching and session management.
- *
- * This singleton provides a unified interface for:
- * - Configuration discovery and loading (YAML, TypeScript, JSON)
- * - Session authentication with automatic caching
- * - Configuration validation and merging
- * - Session preservation across reloads
- * - File watching for configuration changes
- *
- * @example
- * ```typescript
- * const configManager = ConfigManager.getInstance();
- *
- * // Load configuration (cached after first call)
- * const config = await configManager.loadConfig({
- *   validate: true,
- *   reportValidation: true,
- * });
- *
- * // Get cached config synchronously
- * const cachedConfig = configManager.getConfig();
- *
- * // Reload with session preservation
- * const reloadedConfig = await configManager.reloadConfig();
- *
- * // Watch for config changes
- * const unwatch = configManager.watchConfig(async (config) => {
- *   console.log("Config changed:", config);
- * });
- * ```
- */
-export class ConfigManager {
-    // ──────────────────────────────────────────────────
-    // SINGLETON PATTERN
-    // ──────────────────────────────────────────────────
-    static instance = null;
-    /**
-     * Get the ConfigManager singleton instance
-     *
-     * @returns The singleton ConfigManager instance
-     *
-     * @example
-     * ```typescript
-     * const configManager = ConfigManager.getInstance();
-     * ```
-     */
-    static getInstance() {
-        if (!ConfigManager.instance) {
-            ConfigManager.instance = new ConfigManager();
-        }
-        return ConfigManager.instance;
-    }
-    /**
-     * Reset the singleton instance (useful for testing)
-     *
-     * @example
-     * ```typescript
-     * ConfigManager.resetInstance();
-     * const newInstance = ConfigManager.getInstance();
-     * ```
-     */
-    static resetInstance() {
-        ConfigManager.instance = null;
-    }
-    // ──────────────────────────────────────────────────
-    // STATE (Private)
-    // ──────────────────────────────────────────────────
-    cachedConfig = null;
-    cachedConfigPath = null;
-    cachedSession = null;
-    lastLoadTimestamp = 0;
-    isInitialized = false;
-    // Service dependencies
-    discoveryService;
-    loaderService;
-    validationService;
-    sessionService;
-    mergeService;
-    // ──────────────────────────────────────────────────
-    // CONSTRUCTOR
-    // ──────────────────────────────────────────────────
-    /**
-     * Private constructor to enforce singleton pattern.
-     * Use ConfigManager.getInstance() instead.
-     */
-    constructor() {
-        // Initialize all services
-        this.discoveryService = new ConfigDiscoveryService();
-        this.loaderService = new ConfigLoaderService();
-        this.validationService = new ConfigValidationService();
-        this.sessionService = new SessionAuthService();
-        this.mergeService = new ConfigMergeService();
-        logger.debug("ConfigManager instance created", { prefix: "ConfigManager" });
-    }
-    // ──────────────────────────────────────────────────
-    // CORE CONFIGURATION METHODS
-    // ──────────────────────────────────────────────────
-    /**
-     * Load configuration with intelligent caching and session management.
-     *
-     * This method orchestrates the entire configuration loading flow:
-     * 1. Returns cached config if available (unless forceReload is true)
-     * 2. Discovers config file using ConfigDiscoveryService
-     * 3. Loads config from file using ConfigLoaderService
-     * 4. Loads and merges session authentication using SessionAuthService
-     * 5. Applies CLI/environment overrides using ConfigMergeService
-     * 6. Validates configuration if requested
-     * 7. Caches the result for future calls
-     *
-     * @param options - Configuration loading options
-     * @returns The loaded and processed configuration
-     * @throws Error if no configuration file is found
-     * @throws Error if validation fails in strict mode
-     *
-     * @example
-     * ```typescript
-     * const config = await configManager.loadConfig({
-     *   configDir: process.cwd(),
-     *   validate: true,
-     *   strictMode: true,
-     *   reportValidation: true,
-     *   overrides: {
-     *     appwriteEndpoint: "https://custom.endpoint.com/v1"
-     *   }
-     * });
-     * ```
-     */
-    async loadConfig(options = {}) {
-        // 1. Return cache if available and not forcing reload
-        if (this.cachedConfig && !options.forceReload) {
-            logger.debug("Returning cached config", { prefix: "ConfigManager" });
-            return this.getCachedConfigWithOverrides(options.overrides);
-        }
-        logger.debug("Loading config from file", { prefix: "ConfigManager", options });
-        // 2. Discover config file
-        const configPath = await this.discoveryService.findConfig(options.configDir || process.cwd(), options.preferJson || false);
-        if (!configPath) {
-            const searchDir = options.configDir || process.cwd();
-            throw new Error(`No Appwrite configuration found in "${searchDir}".\n` +
-                `Searched for: YAML (.appwrite/config.yaml), TypeScript (appwriteConfig.ts), or JSON (appwrite.json).\n` +
-                `Suggestion: Create a configuration file using "npx appwrite-migrate --init" or refer to the documentation.`);
-        }
-        logger.debug(`Config discovered at: ${configPath}`, { prefix: "ConfigManager" });
-        // 3. Load config from file
-        let config = await this.loaderService.loadFromPath(configPath);
-        // 4. Load session authentication
-        const session = options.sessionOverride ||
-            (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject));
-        // 5. Merge session into config
-        if (session) {
-            logger.debug("Merging session authentication into config", { prefix: "ConfigManager" });
-            config = this.mergeService.mergeSession(config, session);
-            this.cachedSession = session;
-        }
-        // 6. Apply CLI/env overrides
-        if (options.overrides) {
-            logger.debug("Applying configuration overrides", { prefix: "ConfigManager" });
-            config = this.mergeService.applyOverrides(config, options.overrides);
-        }
-        // 7. Validate if requested
-        if (options.validate) {
-            logger.debug("Validating configuration", { prefix: "ConfigManager", strictMode: options.strictMode });
-            const validation = options.strictMode
-                ? this.validationService.validateStrict(config)
-                : this.validationService.validate(config);
-            if (options.reportValidation) {
-                this.validationService.reportResults(validation, { verbose: false });
-            }
-            if (options.strictMode && !validation.isValid) {
-                throw new Error(`Configuration validation failed in strict mode.\n` +
-                    `Errors: ${validation.errors.length}, Warnings: ${validation.warnings.length}\n` +
-                    `Run with reportValidation: true to see details.`);
-            }
-        }
-        // 8. Run version detection and set apiMode if not explicitly configured
-        if (!config.apiMode || config.apiMode === 'auto') {
-            try {
-                logger.debug('Running version detection for API mode detection', {
-                    prefix: "ConfigManager",
-                    endpoint: config.appwriteEndpoint
-                });
-                const versionResult = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey);
-                config.apiMode = versionResult.apiMode;
-                logger.info(`API mode detected: ${config.apiMode}`, {
-                    prefix: "ConfigManager",
-                    method: versionResult.detectionMethod,
-                    confidence: versionResult.confidence,
-                    serverVersion: versionResult.serverVersion,
-                });
-            }
-            catch (error) {
-                logger.warn('Version detection failed, defaulting to legacy mode', {
-                    prefix: "ConfigManager",
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                });
-                config.apiMode = 'legacy';
-            }
-        }
-        // 8. Cache the config
-        this.cachedConfig = config;
-        this.cachedConfigPath = configPath;
-        this.lastLoadTimestamp = Date.now();
-        this.isInitialized = true;
-        logger.debug("Config loaded and cached successfully", {
-            prefix: "ConfigManager",
-            path: configPath,
-            hasSession: !!session,
-        });
-        return config;
-    }
-    /**
-     * Get the cached configuration synchronously.
-     *
-     * @returns The cached configuration
-     * @throws Error if configuration has not been loaded yet
-     *
-     * @example
-     * ```typescript
-     * const config = configManager.getConfig();
-     * ```
-     */
-    getConfig() {
-        if (!this.cachedConfig) {
-            throw new Error("Configuration not loaded. Call loadConfig() first.\n" +
-                "Suggestion: await configManager.loadConfig();");
-        }
-        return this.cachedConfig;
-    }
-    /**
-     * Get the path to the loaded configuration file.
-     *
-     * @returns The configuration file path, or null if not loaded
-     *
-     * @example
-     * ```typescript
-     * const configPath = configManager.getConfigPath();
-     * console.log(`Config loaded from: ${configPath}`);
-     * ```
-     */
-    getConfigPath() {
-        return this.cachedConfigPath;
-    }
-    /**
-     * Check if configuration has been loaded.
-     *
-     * @returns True if configuration is loaded and cached
-     *
-     * @example
-     * ```typescript
-     * if (!configManager.hasConfig()) {
-     *   await configManager.loadConfig();
-     * }
-     * ```
-     */
-    hasConfig() {
-        return this.cachedConfig !== null;
-    }
-    /**
-     * Check if the ConfigManager has been initialized.
-     *
-     * @returns True if initialized (config loaded at least once)
-     *
-     * @example
-     * ```typescript
-     * if (configManager.isConfigInitialized()) {
-     *   console.log("Config ready");
-     * }
-     * ```
-     */
-    isConfigInitialized() {
-        return this.isInitialized;
-    }
-    /**
-     * Invalidate the configuration cache.
-     * Next call to loadConfig() will reload from disk.
-     *
-     * @example
-     * ```typescript
-     * configManager.invalidateCache();
-     * const freshConfig = await configManager.loadConfig();
-     * ```
-     */
-    invalidateCache() {
-        logger.debug("Invalidating config cache", { prefix: "ConfigManager" });
-        this.cachedConfig = null;
-        this.cachedConfigPath = null;
-        this.lastLoadTimestamp = 0;
-        // Note: session cache is preserved by SessionAuthService
-    }
-    /**
-     * Reload configuration from disk, preserving current session.
-     *
-     * This is a convenience method that combines invalidation and reloading
-     * while automatically preserving the current session authentication.
-     *
-     * @param options - Configuration loading options (forceReload is automatically set)
-     * @returns The reloaded configuration
-     *
-     * @example
-     * ```typescript
-     * // Reload config after manual file changes
-     * const config = await configManager.reloadConfig({
-     *   validate: true,
-     *   reportValidation: true
-     * });
-     * ```
-     */
-    async reloadConfig(options = {}) {
-        logger.debug("Reloading config with session preservation", { prefix: "ConfigManager" });
-        // Preserve current session during reload
-        const currentSession = this.cachedSession;
-        return this.loadConfig({
-            ...options,
-            forceReload: true,
-            sessionOverride: currentSession || undefined,
-        });
-    }
-    // ──────────────────────────────────────────────────
-    // SESSION MANAGEMENT
-    // ──────────────────────────────────────────────────
-    /**
-     * Get the current session information.
-     *
-     * @returns The cached session info, or null if no session
-     *
-     * @example
-     * ```typescript
-     * const session = configManager.getSession();
-     * if (session) {
-     *   console.log(`Authenticated as: ${session.email}`);
-     * }
-     * ```
-     */
-    getSession() {
-        return this.cachedSession;
-    }
-    /**
-     * Check if a session is available.
-     *
-     * @returns True if a session is cached
-     *
-     * @example
-     * ```typescript
-     * if (configManager.hasSession()) {
-     *   console.log("Using session authentication");
-     * } else {
-     *   console.log("Using API key authentication");
-     * }
-     * ```
-     */
-    hasSession() {
-        return this.cachedSession !== null;
-    }
-    /**
-     * Refresh session from disk (bypasses session cache).
-     *
-     * This forces SessionAuthService to reload from ~/.appwrite/prefs.json
-     * and update the cached session.
-     *
-     * @returns The refreshed session, or null if no session found
-     *
-     * @example
-     * ```typescript
-     * // After logging in via appwrite CLI
-     * const session = await configManager.refreshSession();
-     * if (session) {
-     *   console.log("Session refreshed successfully");
-     * }
-     * ```
-     */
-    async refreshSession() {
-        if (!this.cachedConfig) {
-            logger.debug("Cannot refresh session - no config loaded", { prefix: "ConfigManager" });
-            return null;
-        }
-        logger.debug("Refreshing session from disk", { prefix: "ConfigManager" });
-        // Invalidate session cache
-        this.sessionService.invalidateCache();
-        // Reload session
-        const session = await this.sessionService.findSession(this.cachedConfig.appwriteEndpoint, this.cachedConfig.appwriteProject);
-        if (session) {
-            this.cachedSession = session;
-            logger.debug("Session refreshed successfully", { prefix: "ConfigManager" });
-        }
-        else {
-            this.cachedSession = null;
-            logger.debug("No session found after refresh", { prefix: "ConfigManager" });
-        }
-        return session;
-    }
-    /**
-     * Get authentication status for the current configuration.
-     *
-     * @returns Authentication status object with details about current auth method
-     * @throws Error if configuration has not been loaded
-     *
-     * @example
-     * ```typescript
-     * const authStatus = await configManager.getAuthStatus();
-     * console.log(`Auth method: ${authStatus.authMethod}`);
-     * console.log(`Has valid session: ${authStatus.hasValidSession}`);
-     * ```
-     */
-    async getAuthStatus() {
-        if (!this.cachedConfig) {
-            throw new Error("Configuration not loaded. Call loadConfig() first.\n" +
-                "Suggestion: await configManager.loadConfig();");
-        }
-        return await this.sessionService.getAuthenticationStatus(this.cachedConfig.appwriteEndpoint, this.cachedConfig.appwriteProject, this.cachedConfig.appwriteKey, this.cachedSession);
-    }
-    /**
-     * Clear the cached session.
-     * Next load will attempt to find a new session.
-     *
-     * @example
-     * ```typescript
-     * configManager.clearSession();
-     * const config = await configManager.reloadConfig();
-     * ```
-     */
-    clearSession() {
-        logger.debug("Clearing cached session", { prefix: "ConfigManager" });
-        this.cachedSession = null;
-    }
-    // ──────────────────────────────────────────────────
-    // VALIDATION
-    // ──────────────────────────────────────────────────
-    /**
-     * Validate the current configuration (warnings allowed).
-     *
-     * @param reportResults - Whether to report validation results to console
-     * @returns Validation result with errors and warnings
-     * @throws Error if configuration has not been loaded
-     *
-     * @example
-     * ```typescript
-     * const validation = configManager.validateConfig(true);
-     * if (!validation.isValid) {
-     *   console.log(`Found ${validation.errors.length} errors`);
-     * }
-     * ```
-     */
-    validateConfig(reportResults = false) {
-        if (!this.cachedConfig) {
-            throw new Error("Configuration not loaded. Call loadConfig() first.\n" +
-                "Suggestion: await configManager.loadConfig();");
-        }
-        const validation = this.validationService.validate(this.cachedConfig);
-        if (reportResults) {
-            this.validationService.reportResults(validation);
-        }
-        return validation;
-    }
-    /**
-     * Validate the current configuration in strict mode (warnings as errors).
-     *
-     * @param reportResults - Whether to report validation results to console
-     * @returns Validation result with errors and warnings (warnings treated as errors)
-     * @throws Error if configuration has not been loaded
-     *
-     * @example
-     * ```typescript
-     * const validation = configManager.validateConfigStrict(true);
-     * if (!validation.isValid) {
-     *   console.log("Config validation failed (strict mode)");
-     * }
-     * ```
-     */
-    validateConfigStrict(reportResults = false) {
-        if (!this.cachedConfig) {
-            throw new Error("Configuration not loaded. Call loadConfig() first.\n" +
-                "Suggestion: await configManager.loadConfig();");
-        }
-        const validation = this.validationService.validateStrict(this.cachedConfig);
-        if (reportResults) {
-            this.validationService.reportResults(validation);
-        }
-        return validation;
-    }
-    // ──────────────────────────────────────────────────
-    // ADVANCED / CONVENIENCE
-    // ──────────────────────────────────────────────────
-    /**
-     * Watch configuration file for changes and reload automatically.
-     *
-     * Returns a function to stop watching.
-     *
-     * @param callback - Function to call when config changes
-     * @returns Function to stop watching
-     *
-     * @example
-     * ```typescript
-     * const unwatch = configManager.watchConfig(async (config) => {
-     *   console.log("Config changed, reloading...");
-     *   // Handle config change
-     * });
-     *
-     * // Later, stop watching
-     * unwatch();
-     * ```
-     */
-    watchConfig(callback) {
-        if (!this.cachedConfigPath) {
-            throw new Error("Cannot watch config - no config file loaded.\n" +
-                "Suggestion: Call loadConfig() before watchConfig().");
-        }
-        const configPath = this.cachedConfigPath;
-        logger.debug(`Setting up config file watcher: ${configPath}`, { prefix: "ConfigManager" });
-        let isProcessing = false;
-        const watcher = fs.watch(configPath, async (eventType) => {
-            if (eventType === "change" && !isProcessing) {
-                isProcessing = true;
-                logger.debug("Config file changed, reloading...", { prefix: "ConfigManager" });
-                try {
-                    const newConfig = await this.reloadConfig();
-                    await callback(newConfig);
-                }
-                catch (error) {
-                    MessageFormatter.error("Failed to reload config after file change", error instanceof Error ? error : String(error), { prefix: "ConfigManager" });
-                }
-                finally {
-                    isProcessing = false;
-                }
-            }
-        });
-        // Return cleanup function
-        return () => {
-            logger.debug("Stopping config file watcher", { prefix: "ConfigManager" });
-            watcher.close();
-        };
-    }
-    /**
-     * Merge overrides into the current configuration without persisting.
-     *
-     * This creates a new config object with overrides applied, without
-     * affecting the cached configuration.
-     *
-     * @param overrides - Configuration overrides to apply
-     * @returns New configuration with overrides applied
-     * @throws Error if configuration has not been loaded
-     *
-     * @example
-     * ```typescript
-     * const customConfig = configManager.mergeOverrides({
-     *   appwriteEndpoint: "https://test.endpoint.com/v1"
-     * });
-     * ```
-     */
-    mergeOverrides(overrides) {
-        if (!this.cachedConfig) {
-            throw new Error("Configuration not loaded. Call loadConfig() first.\n" +
-                "Suggestion: await configManager.loadConfig();");
-        }
-        return this.mergeService.applyOverrides(this.cachedConfig, overrides);
-    }
-    /**
-     * Get collections from the configuration, optionally filtered.
-     *
-     * @param filter - Optional filter function for collections
-     * @returns Array of collections (or tables, depending on API mode)
-     *
-     * @example
-     * ```typescript
-     * // Get all collections
-     * const allCollections = configManager.getCollections();
-     *
-     * // Get enabled collections only
-     * const enabledCollections = configManager.getCollections(
-     *   (c) => c.enabled !== false
-     * );
-     * ```
-     */
-    getCollections(filter) {
-        const config = this.getConfig();
-        const collections = config.collections || config.tables || [];
-        if (filter) {
-            return collections.filter(filter);
-        }
-        return collections;
-    }
-    /**
-     * Get databases from the configuration.
-     *
-     * @returns Array of databases
-     *
-     * @example
-     * ```typescript
-     * const databases = configManager.getDatabases();
-     * console.log(`Found ${databases.length} databases`);
-     * ```
-     */
-    getDatabases() {
-        const config = this.getConfig();
-        return config.databases || [];
-    }
-    /**
-     * Get buckets from the configuration.
-     *
-     * @returns Array of buckets
-     *
-     * @example
-     * ```typescript
-     * const buckets = configManager.getBuckets();
-     * console.log(`Found ${buckets.length} buckets`);
-     * ```
-     */
-    getBuckets() {
-        const config = this.getConfig();
-        return config.buckets || [];
-    }
-    /**
-     * Get functions from the configuration.
-     *
-     * @returns Array of functions
-     *
-     * @example
-     * ```typescript
-     * const functions = configManager.getFunctions();
-     * console.log(`Found ${functions.length} functions`);
-     * ```
-     */
-    getFunctions() {
-        const config = this.getConfig();
-        return config.functions || [];
-    }
-    // ──────────────────────────────────────────────────
-    // PRIVATE HELPERS
-    // ──────────────────────────────────────────────────
-    /**
-     * Get cached config with optional overrides applied.
-     * Used internally to avoid reloading when only overrides change.
-     */
-    getCachedConfigWithOverrides(overrides) {
-        if (!this.cachedConfig) {
-            throw new Error("No cached config available");
-        }
-        if (!overrides) {
-            return this.cachedConfig;
-        }
-        logger.debug("Applying overrides to cached config", { prefix: "ConfigManager" });
-        return this.mergeService.applyOverrides(this.cachedConfig, overrides);
-    }
-}