appwrite-utils-cli 1.6.3 → 1.6.4

package/dist/config/ConfigManager.js

@@ -0,0 +1,625 @@
+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";
+/**
+ * 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 = this.discoveryService.findConfig(options.configDir || process.cwd());
+        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. 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);
+    }
+}

package/dist/config/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration Management
+ *
+ * Centralized configuration manager with services for discovery, loading, validation, and merging.
+ */
+export { ConfigManager } from "./ConfigManager.js";
+export type { ConfigLoadOptions, CollectionFilter } from "./ConfigManager.js";
+export * from "./services/index.js";

package/dist/config/index.js

@@ -0,0 +1,7 @@
+/**
+ * Configuration Management
+ *
+ * Centralized configuration manager with services for discovery, loading, validation, and merging.
+ */
+export { ConfigManager } from "./ConfigManager.js";
+export * from "./services/index.js";