appwrite-utils-cli 1.6.3 → 1.6.5

package/dist/config/services/ConfigLoaderService.js

@@ -0,0 +1,410 @@
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import { register } from "tsx/esm/api";
+import { pathToFileURL } from "node:url";
+import { MessageFormatter } from "../../shared/messageFormatter.js";
+import { normalizeYamlData } from "../../utils/yamlConverter.js";
+import { loadYamlConfig } from "../yamlConfig.js";
+import { loadAppwriteProjectConfig, projectConfigToAppwriteConfig, getCollectionsFromProject } from "../../utils/projectConfig.js";
+import { loadYamlCollection, loadYamlTable, } from "../../utils/configDiscovery.js";
+/**
+ * Service for loading and parsing Appwrite configuration files.
+ *
+ * Supports:
+ * - YAML configuration files (.appwrite/config.yaml)
+ * - TypeScript configuration files (appwriteConfig.ts)
+ * - JSON project configuration files (appwrite.json)
+ * - Collection and table YAML/TypeScript definitions
+ *
+ * Features:
+ * - Auto-detects configuration file type
+ * - Converts between different configuration formats
+ * - Loads collections and tables from directories
+ * - Handles session preservation
+ * - Validates and normalizes configuration data
+ */
+export class ConfigLoaderService {
+    /**
+     * Loads configuration from a discovered path, auto-detecting the type
+     * @param configPath Path to the configuration file
+     * @param sessionOptions Optional session preservation options
+     * @returns Parsed AppwriteConfig
+     */
+    async loadFromPath(configPath, sessionOptions) {
+        const ext = path.extname(configPath).toLowerCase();
+        // Determine file type and load accordingly
+        if (ext === ".yaml" || ext === ".yml") {
+            return this.loadYaml(configPath, sessionOptions);
+        }
+        else if (ext === ".ts") {
+            return this.loadTypeScript(configPath);
+        }
+        else if (ext === ".json") {
+            const partialConfig = await this.loadProjectConfig(configPath);
+            // Convert partial config to full AppwriteConfig with sensible defaults
+            if (!partialConfig.appwriteEndpoint || !partialConfig.appwriteProject) {
+                throw new Error("JSON project config must contain at minimum 'endpoint' and 'projectId' fields");
+            }
+            return {
+                appwriteEndpoint: partialConfig.appwriteEndpoint,
+                appwriteProject: partialConfig.appwriteProject,
+                appwriteKey: partialConfig.appwriteKey || "",
+                apiMode: partialConfig.apiMode || "auto",
+                appwriteClient: null,
+                logging: partialConfig.logging || {
+                    enabled: false,
+                    level: "info",
+                    console: false,
+                },
+                enableBackups: partialConfig.enableBackups ?? true,
+                backupInterval: partialConfig.backupInterval || 3600,
+                backupRetention: partialConfig.backupRetention || 30,
+                enableBackupCleanup: partialConfig.enableBackupCleanup ?? true,
+                enableMockData: partialConfig.enableMockData || false,
+                documentBucketId: partialConfig.documentBucketId || "documents",
+                usersCollectionName: partialConfig.usersCollectionName || "Members",
+                schemaConfig: partialConfig.schemaConfig || {
+                    outputDirectory: "schemas",
+                    yamlSchemaDirectory: ".yaml_schemas",
+                    importDirectory: "importData",
+                    collectionsDirectory: "collections",
+                    tablesDirectory: "tables",
+                },
+                databases: partialConfig.databases || [],
+                buckets: partialConfig.buckets || [],
+                functions: partialConfig.functions || [],
+                collections: partialConfig.collections || [],
+                sessionCookie: partialConfig.sessionCookie,
+                authMethod: partialConfig.authMethod || "auto",
+                sessionMetadata: partialConfig.sessionMetadata,
+            };
+        }
+        throw new Error(`Unsupported configuration file type: ${ext}`);
+    }
+    /**
+     * Loads a YAML configuration file
+     * @param yamlPath Path to the YAML config file
+     * @param sessionOptions Optional session preservation options
+     * @returns Parsed AppwriteConfig
+     */
+    async loadYaml(yamlPath, sessionOptions) {
+        if (!fs.existsSync(yamlPath)) {
+            throw new Error(`YAML config file not found: ${yamlPath}`);
+        }
+        try {
+            const config = await loadYamlConfig(yamlPath);
+            if (!config) {
+                throw new Error(`Failed to load YAML config from: ${yamlPath}`);
+            }
+            // Apply session preservation if provided
+            if (sessionOptions) {
+                if (sessionOptions.sessionCookie) {
+                    config.sessionCookie = sessionOptions.sessionCookie;
+                }
+                if (sessionOptions.authMethod) {
+                    config.authMethod = sessionOptions.authMethod;
+                }
+                if (sessionOptions.sessionMetadata) {
+                    config.sessionMetadata = {
+                        ...config.sessionMetadata,
+                        ...sessionOptions.sessionMetadata,
+                    };
+                }
+            }
+            MessageFormatter.success(`Loaded YAML config from: ${yamlPath}`, {
+                prefix: "Config",
+            });
+            return config;
+        }
+        catch (error) {
+            MessageFormatter.error(`Error loading YAML config from ${yamlPath}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+            throw error;
+        }
+    }
+    /**
+     * Loads a TypeScript configuration file
+     * @param tsPath Path to the TypeScript config file
+     * @returns Parsed AppwriteConfig
+     */
+    async loadTypeScript(tsPath) {
+        if (!fs.existsSync(tsPath)) {
+            throw new Error(`TypeScript config file not found: ${tsPath}`);
+        }
+        const unregister = register(); // Register tsx enhancement
+        try {
+            const configUrl = pathToFileURL(tsPath).href;
+            const configModule = await import(configUrl);
+            const config = configModule.default?.default || configModule.default || configModule;
+            if (!config) {
+                throw new Error(`Failed to load TypeScript config from: ${tsPath}`);
+            }
+            MessageFormatter.success(`Loaded TypeScript config from: ${tsPath}`, {
+                prefix: "Config",
+            });
+            return config;
+        }
+        catch (error) {
+            MessageFormatter.error(`Error loading TypeScript config from ${tsPath}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+            throw error;
+        }
+        finally {
+            unregister(); // Unregister tsx when done
+        }
+    }
+    /**
+     * Loads an appwrite.json project configuration file
+     * Converts projectId → appwriteProject and detects API mode
+     * @param jsonPath Path to the JSON config file
+     * @returns Partial AppwriteConfig (requires merging with defaults)
+     */
+    async loadProjectConfig(jsonPath) {
+        if (!fs.existsSync(jsonPath)) {
+            throw new Error(`JSON config file not found: ${jsonPath}`);
+        }
+        try {
+            const projectConfig = loadAppwriteProjectConfig(jsonPath);
+            if (!projectConfig) {
+                throw new Error(`Failed to load project config from: ${jsonPath}`);
+            }
+            // Convert project config to AppwriteConfig format
+            const appwriteConfig = projectConfigToAppwriteConfig(projectConfig);
+            // Get collections from project config
+            const collections = getCollectionsFromProject(projectConfig);
+            if (collections.length > 0) {
+                appwriteConfig.collections = collections;
+            }
+            MessageFormatter.success(`Loaded project config from: ${jsonPath}`, {
+                prefix: "Config",
+            });
+            return appwriteConfig;
+        }
+        catch (error) {
+            MessageFormatter.error(`Error loading project config from ${jsonPath}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+            throw error;
+        }
+    }
+    /**
+     * Loads all collections from a collections/ directory
+     * Supports both YAML (.yaml, .yml) and TypeScript (.ts) files
+     * @param collectionsDir Path to the collections directory
+     * @param options Loading options
+     * @returns Array of loaded Collection objects
+     */
+    async loadCollections(collectionsDir, options = {}) {
+        if (!fs.existsSync(collectionsDir)) {
+            MessageFormatter.debug(`Collections directory not found: ${collectionsDir}`, { prefix: "Config" });
+            return [];
+        }
+        const collections = [];
+        const unregister = register(); // Register tsx for TypeScript collections
+        try {
+            const collectionFiles = fs.readdirSync(collectionsDir);
+            MessageFormatter.success(`Loading from collections directory: ${collectionFiles.length} files found`, { prefix: "Config" });
+            for (const file of collectionFiles) {
+                if (file === "index.ts") {
+                    continue;
+                }
+                const filePath = path.join(collectionsDir, file);
+                let collection = null;
+                // Handle YAML collections
+                if (file.endsWith(".yaml") || file.endsWith(".yml")) {
+                    collection = loadYamlCollection(filePath);
+                }
+                // Handle TypeScript collections
+                else if (file.endsWith(".ts")) {
+                    try {
+                        const fileUrl = pathToFileURL(filePath).href;
+                        const collectionModule = await import(fileUrl);
+                        const importedCollection = collectionModule.default?.default ||
+                            collectionModule.default ||
+                            collectionModule;
+                        if (importedCollection) {
+                            collection = importedCollection;
+                            // Ensure importDefs are properly loaded
+                            if (collectionModule.importDefs || collection.importDefs) {
+                                collection.importDefs =
+                                    collectionModule.importDefs || collection.importDefs;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        MessageFormatter.error(`Error loading TypeScript collection: ${file}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+                    }
+                }
+                if (collection) {
+                    const collectionName = collection.name || collection.$id || file;
+                    // Check for naming conflicts if existingNames provided
+                    if (options.existingNames?.has(collectionName)) {
+                        MessageFormatter.warning(`Skipping duplicate collection '${collectionName}' (already loaded)`, { prefix: "Config" });
+                        continue;
+                    }
+                    // Mark as tables if requested
+                    if (options.markAsTablesDir) {
+                        collection._isFromTablesDir = true;
+                    }
+                    collections.push(collection);
+                }
+            }
+            MessageFormatter.success(`Loaded ${collections.length} collection(s) from ${collectionsDir}`, { prefix: "Config" });
+        }
+        catch (error) {
+            MessageFormatter.error(`Error loading collections from ${collectionsDir}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+        }
+        finally {
+            unregister(); // Unregister tsx when done
+        }
+        return collections;
+    }
+    /**
+     * Loads all tables from a tables/ directory
+     * Supports both YAML (.yaml, .yml) and TypeScript (.ts) files
+     * @param tablesDir Path to the tables directory
+     * @param options Loading options
+     * @returns Array of loaded table objects
+     */
+    async loadTables(tablesDir, options = {}) {
+        if (!fs.existsSync(tablesDir)) {
+            MessageFormatter.debug(`Tables directory not found: ${tablesDir}`, {
+                prefix: "Config",
+            });
+            return [];
+        }
+        const tables = [];
+        const unregister = register(); // Register tsx for TypeScript tables
+        try {
+            const tableFiles = fs.readdirSync(tablesDir);
+            MessageFormatter.success(`Loading from tables directory: ${tableFiles.length} files found`, { prefix: "Config" });
+            for (const file of tableFiles) {
+                if (file === "index.ts") {
+                    continue;
+                }
+                const filePath = path.join(tablesDir, file);
+                let table = null;
+                // Handle YAML tables
+                if (file.endsWith(".yaml") || file.endsWith(".yml")) {
+                    table = loadYamlTable(filePath);
+                }
+                // Handle TypeScript tables
+                else if (file.endsWith(".ts")) {
+                    try {
+                        const fileUrl = pathToFileURL(filePath).href;
+                        const tableModule = await import(fileUrl);
+                        const importedTable = tableModule.default?.default || tableModule.default || tableModule;
+                        if (importedTable) {
+                            table = importedTable;
+                            // Ensure importDefs are properly loaded
+                            if (tableModule.importDefs || table.importDefs) {
+                                table.importDefs = tableModule.importDefs || table.importDefs;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        MessageFormatter.error(`Error loading TypeScript table: ${file}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+                    }
+                }
+                if (table) {
+                    const tableName = table.name || table.tableId || table.$id || file;
+                    // Check for naming conflicts if existingNames provided
+                    if (options.existingNames?.has(tableName)) {
+                        MessageFormatter.warning(`Skipping duplicate table '${tableName}' (already loaded from collections/)`, { prefix: "Config" });
+                        continue;
+                    }
+                    // Always mark tables as coming from tables directory
+                    table._isFromTablesDir = true;
+                    tables.push(table);
+                }
+            }
+            MessageFormatter.success(`Loaded ${tables.length} table(s) from ${tablesDir}`, { prefix: "Config" });
+        }
+        catch (error) {
+            MessageFormatter.error(`Error loading tables from ${tablesDir}`, error instanceof Error ? error : undefined, { prefix: "Config" });
+        }
+        finally {
+            unregister(); // Unregister tsx when done
+        }
+        return tables;
+    }
+    /**
+     * Loads collections and tables with conflict detection
+     * Collections take priority over tables when names conflict
+     * @param collectionsDir Path to collections directory
+     * @param tablesDir Path to tables directory
+     * @returns Object containing combined arrays and conflict information
+     */
+    async loadCollectionsAndTables(collectionsDir, tablesDir) {
+        const items = [];
+        const loadedNames = new Set();
+        const conflicts = [];
+        // Load from collections/ directory first (higher priority)
+        if (fs.existsSync(collectionsDir)) {
+            const collections = await this.loadCollections(collectionsDir);
+            for (const collection of collections) {
+                const name = collection.name || collection.$id || "";
+                loadedNames.add(name);
+                items.push(collection);
+            }
+        }
+        // Load from tables/ directory second (lower priority, check for conflicts)
+        if (fs.existsSync(tablesDir)) {
+            const tables = await this.loadTables(tablesDir, {
+                existingNames: loadedNames,
+                markAsTablesDir: true,
+            });
+            for (const table of tables) {
+                const name = table.name || table.tableId || table.$id || "";
+                // Check for conflicts
+                if (loadedNames.has(name)) {
+                    conflicts.push({
+                        name,
+                        source1: "collections/",
+                        source2: "tables/",
+                    });
+                }
+                else {
+                    loadedNames.add(name);
+                    items.push(table);
+                }
+            }
+        }
+        const fromCollections = items.filter((item) => !item._isFromTablesDir)
+            .length;
+        const fromTables = items.filter((item) => item._isFromTablesDir).length;
+        return {
+            items,
+            fromCollections,
+            fromTables,
+            conflicts,
+        };
+    }
+    /**
+     * Validates that a configuration file can be loaded
+     * @param configPath Path to the configuration file
+     * @returns True if the file can be loaded, false otherwise
+     */
+    canLoadConfig(configPath) {
+        if (!fs.existsSync(configPath)) {
+            return false;
+        }
+        const ext = path.extname(configPath).toLowerCase();
+        return ext === ".yaml" || ext === ".yml" || ext === ".ts" || ext === ".json";
+    }
+    /**
+     * Gets the type of a configuration file
+     * @param configPath Path to the configuration file
+     * @returns Configuration type or null if unknown
+     */
+    getConfigType(configPath) {
+        const ext = path.extname(configPath).toLowerCase();
+        if (ext === ".yaml" || ext === ".yml") {
+            return "yaml";
+        }
+        else if (ext === ".ts") {
+            return "typescript";
+        }
+        else if (ext === ".json") {
+            return "json";
+        }
+        return null;
+    }
+}

package/dist/config/services/ConfigMergeService.d.ts

@@ -0,0 +1,208 @@
+import type { AppwriteConfig } from "appwrite-utils";
+import type { SessionAuthInfo } from "./SessionAuthService.js";
+/**
+ * Configuration override options that can be applied from CLI arguments or environment
+ */
+export interface ConfigOverrides {
+    /** Appwrite endpoint URL (e.g., https://cloud.appwrite.io/v1) */
+    appwriteEndpoint?: string;
+    /** Appwrite project ID */
+    appwriteProject?: string;
+    /** API key for authentication */
+    appwriteKey?: string;
+    /** Session cookie for authentication */
+    sessionCookie?: string;
+    /** Explicitly set authentication method */
+    authMethod?: "session" | "apikey" | "auto";
+}
+/**
+ * Service responsible for merging configuration from multiple sources with proper priority handling.
+ *
+ * @description
+ * Handles configuration merging with the following priority order (highest to lowest):
+ * 1. CLI arguments/overrides (--endpoint, --apiKey, etc.)
+ * 2. Session cookie from ~/.appwrite/prefs.json
+ * 3. Config file values (YAML/TS/JSON)
+ * 4. Environment variables (APPWRITE_ENDPOINT, APPWRITE_PROJECT, etc.)
+ *
+ * The service ensures proper deep merging of nested objects while preserving array order
+ * and preventing undefined/null values from overwriting existing values.
+ *
+ * @example
+ * ```typescript
+ * const mergeService = new ConfigMergeService();
+ *
+ * // Merge session into config
+ * const configWithSession = mergeService.mergeSession(baseConfig, sessionInfo);
+ *
+ * // Apply CLI overrides
+ * const finalConfig = mergeService.applyOverrides(configWithSession, {
+ *   appwriteEndpoint: 'https://custom-endpoint.com/v1',
+ *   appwriteKey: 'custom-api-key'
+ * });
+ * ```
+ */
+export declare class ConfigMergeService {
+    /**
+     * Merges session authentication information into an existing configuration.
+     *
+     * @description
+     * Adds session authentication details to the configuration, setting:
+     * - sessionCookie: The authentication cookie from the session
+     * - authMethod: Set to "session" to indicate session-based auth
+     *
+     * The session endpoint and projectId are used for validation but not merged
+     * since they should match the config's values.
+     *
+     * @param config - Base configuration to merge session into
+     * @param session - Session authentication information
+     * @returns New configuration object with session merged (input config is not mutated)
+     *
+     * @example
+     * ```typescript
+     * const configWithSession = mergeService.mergeSession(config, {
+     *   projectId: "my-project",
+     *   endpoint: "https://cloud.appwrite.io/v1",
+     *   sessionCookie: "eyJhbGc...",
+     *   email: "user@example.com"
+     * });
+     * ```
+     */
+    mergeSession(config: AppwriteConfig, session: SessionAuthInfo): AppwriteConfig;
+    /**
+     * Applies configuration overrides from CLI arguments or programmatic sources.
+     *
+     * @description
+     * Applies high-priority overrides that take precedence over all other config sources.
+     * Only applies values that are explicitly set (not undefined or null).
+     *
+     * This method is typically used to apply CLI arguments like:
+     * - --endpoint
+     * - --apiKey
+     * - --project
+     *
+     * @param config - Base configuration to apply overrides to
+     * @param overrides - Override values to apply
+     * @returns New configuration object with overrides applied (input config is not mutated)
+     *
+     * @example
+     * ```typescript
+     * const overriddenConfig = mergeService.applyOverrides(config, {
+     *   appwriteEndpoint: 'https://custom.appwrite.io/v1',
+     *   appwriteKey: 'my-api-key',
+     *   authMethod: 'apikey'
+     * });
+     * ```
+     */
+    applyOverrides(config: AppwriteConfig, overrides: ConfigOverrides): AppwriteConfig;
+    /**
+     * Merges environment variables into the configuration.
+     *
+     * @description
+     * Reads environment variables and merges them into the config with the lowest priority.
+     * Only applies environment variables that are set and have non-empty values.
+     *
+     * Supported environment variables:
+     * - APPWRITE_ENDPOINT: Appwrite API endpoint URL
+     * - APPWRITE_PROJECT: Appwrite project ID
+     * - APPWRITE_API_KEY: API key for authentication
+     * - APPWRITE_SESSION_COOKIE: Session cookie for authentication
+     *
+     * Environment variables are only applied if the corresponding config value is not already set.
+     *
+     * @param config - Base configuration to merge environment variables into
+     * @returns New configuration object with environment variables merged (input config is not mutated)
+     *
+     * @example
+     * ```typescript
+     * // With env vars: APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+     * const configWithEnv = mergeService.mergeEnvironmentVariables(config);
+     * // configWithEnv.appwriteEndpoint will be set from env var if not already set
+     * ```
+     */
+    mergeEnvironmentVariables(config: AppwriteConfig): AppwriteConfig;
+    /**
+     * Performs a deep merge of multiple partial configuration sources into a complete configuration.
+     *
+     * @description
+     * Merges multiple configuration sources using a deep merge strategy that:
+     * - Recursively merges nested objects
+     * - Preserves array order (arrays are replaced, not merged)
+     * - Skips undefined and null values (they don't overwrite existing values)
+     * - Later sources in the array take precedence over earlier ones
+     *
+     * This method is useful when combining:
+     * - Base defaults with file-based config
+     * - Multiple configuration files
+     * - Config fragments from different sources
+     *
+     * @param sources - Array of partial configurations to merge (order matters: later sources override earlier ones)
+     * @returns Complete merged configuration object
+     *
+     * @throws {Error} If no valid configuration can be produced from the sources
+     *
+     * @example
+     * ```typescript
+     * const merged = mergeService.mergeSources([
+     *   envConfig,           // Lowest priority
+     *   fileConfig,          // Medium priority
+     *   sessionConfig,       // Higher priority
+     *   overrideConfig       // Highest priority
+     * ]);
+     * ```
+     */
+    mergeSources(sources: Array<Partial<AppwriteConfig>>): AppwriteConfig;
+    /**
+     * Internal helper for deep merging two configuration objects.
+     *
+     * @description
+     * Performs a deep merge of two objects with special handling for:
+     * - Plain objects: Recursively merged
+     * - Arrays: Target array is replaced by source array (not merged)
+     * - Undefined/null values in source: Skipped (don't overwrite target)
+     * - Primitive values: Source overwrites target
+     *
+     * This is used internally by mergeSources but can also be used directly
+     * for specific merge operations.
+     *
+     * @param target - Base configuration object
+     * @param source - Configuration to merge into target
+     * @returns New deeply merged configuration object
+     *
+     * @private
+     */
+    private deepMergeConfigs;
+    /**
+     * Creates a configuration by merging all sources in the correct priority order.
+     *
+     * @description
+     * Convenience method that applies the full configuration merge pipeline:
+     * 1. Start with base config (from file)
+     * 2. Merge environment variables (lowest priority)
+     * 3. Merge session information (if provided)
+     * 4. Apply CLI/programmatic overrides (highest priority)
+     *
+     * This is the recommended way to build a final configuration from all sources.
+     *
+     * @param baseConfig - Configuration loaded from file (YAML/TS/JSON)
+     * @param options - Optional merge options
+     * @param options.session - Session authentication to merge
+     * @param options.overrides - CLI/programmatic overrides to apply
+     * @param options.includeEnv - Whether to include environment variables (default: true)
+     * @returns Final merged configuration with all sources applied in priority order
+     *
+     * @example
+     * ```typescript
+     * const finalConfig = mergeService.mergeAllSources(fileConfig, {
+     *   session: sessionInfo,
+     *   overrides: cliOverrides,
+     *   includeEnv: true
+     * });
+     * ```
+     */
+    mergeAllSources(baseConfig: AppwriteConfig, options?: {
+        session?: SessionAuthInfo;
+        overrides?: ConfigOverrides;
+        includeEnv?: boolean;
+    }): AppwriteConfig;
+}