appwrite-utils-cli 1.6.3 → 1.6.4

package/dist/config/services/ConfigMergeService.js

@@ -0,0 +1,307 @@
+import { merge, cloneDeep, isPlainObject } from "es-toolkit";
+/**
+ * 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 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, session) {
+        // Clone config to avoid mutation
+        const merged = cloneDeep(config);
+        // Add session authentication (map 'cookie' to 'sessionCookie')
+        merged.sessionCookie = session.cookie;
+        merged.authMethod = "session";
+        // Add session metadata if available
+        if (session.email || session.expiresAt) {
+            merged.sessionMetadata = {
+                email: session.email,
+                expiresAt: session.expiresAt,
+            };
+        }
+        return merged;
+    }
+    /**
+     * 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, overrides) {
+        // Clone config to avoid mutation
+        const merged = cloneDeep(config);
+        // Apply each override only if it has a value (not undefined/null)
+        if (overrides.appwriteEndpoint !== undefined && overrides.appwriteEndpoint !== null) {
+            merged.appwriteEndpoint = overrides.appwriteEndpoint;
+        }
+        if (overrides.appwriteProject !== undefined && overrides.appwriteProject !== null) {
+            merged.appwriteProject = overrides.appwriteProject;
+        }
+        if (overrides.appwriteKey !== undefined && overrides.appwriteKey !== null) {
+            merged.appwriteKey = overrides.appwriteKey;
+        }
+        if (overrides.sessionCookie !== undefined && overrides.sessionCookie !== null) {
+            merged.sessionCookie = overrides.sessionCookie;
+        }
+        if (overrides.authMethod !== undefined && overrides.authMethod !== null) {
+            merged.authMethod = overrides.authMethod;
+        }
+        return merged;
+    }
+    /**
+     * 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) {
+        // Clone config to avoid mutation
+        const merged = cloneDeep(config);
+        // Read environment variables
+        const envEndpoint = process.env.APPWRITE_ENDPOINT;
+        const envProject = process.env.APPWRITE_PROJECT;
+        const envApiKey = process.env.APPWRITE_API_KEY;
+        const envSessionCookie = process.env.APPWRITE_SESSION_COOKIE;
+        // Apply environment variables only if not already set in config
+        // Environment variables have the lowest priority
+        if (envEndpoint && !merged.appwriteEndpoint) {
+            merged.appwriteEndpoint = envEndpoint;
+        }
+        if (envProject && !merged.appwriteProject) {
+            merged.appwriteProject = envProject;
+        }
+        if (envApiKey && !merged.appwriteKey) {
+            merged.appwriteKey = envApiKey;
+        }
+        if (envSessionCookie && !merged.sessionCookie) {
+            merged.sessionCookie = envSessionCookie;
+        }
+        return merged;
+    }
+    /**
+     * 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) {
+        // Filter out undefined/null sources
+        const validSources = sources.filter((source) => source !== undefined && source !== null);
+        if (validSources.length === 0) {
+            throw new Error("No valid configuration sources provided for merging");
+        }
+        // Start with an empty base object
+        let merged = {};
+        // Merge each source in order (later sources override earlier ones)
+        for (const source of validSources) {
+            merged = this.deepMergeConfigs(merged, source);
+        }
+        // Validate that we have the minimum required fields
+        if (!merged.appwriteEndpoint || !merged.appwriteProject) {
+            throw new Error("Merged configuration is missing required fields: appwriteEndpoint and/or appwriteProject");
+        }
+        return merged;
+    }
+    /**
+     * 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
+     */
+    deepMergeConfigs(target, source) {
+        // Clone target to avoid mutation
+        const result = cloneDeep(target);
+        // Iterate through source properties
+        for (const key in source) {
+            if (!Object.prototype.hasOwnProperty.call(source, key)) {
+                continue;
+            }
+            const sourceValue = source[key];
+            const targetValue = result[key];
+            // Skip undefined and null values from source
+            if (sourceValue === undefined || sourceValue === null) {
+                continue;
+            }
+            // Handle arrays: Replace target array with source array (don't merge)
+            if (Array.isArray(sourceValue)) {
+                result[key] = cloneDeep(sourceValue);
+                continue;
+            }
+            // Handle plain objects: Recursively merge
+            if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+                result[key] = this.deepMergeConfigs(targetValue, sourceValue);
+                continue;
+            }
+            // For all other cases (primitives, etc.), source overwrites target
+            result[key] = cloneDeep(sourceValue);
+        }
+        return result;
+    }
+    /**
+     * 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, options = {}) {
+        const { session, overrides, includeEnv = true } = options;
+        // Start with base config
+        let config = cloneDeep(baseConfig);
+        // Step 1: Merge environment variables (lowest priority)
+        if (includeEnv) {
+            config = this.mergeEnvironmentVariables(config);
+        }
+        // Step 2: Merge session (medium-high priority)
+        if (session) {
+            config = this.mergeSession(config, session);
+        }
+        // Step 3: Apply overrides (highest priority)
+        if (overrides) {
+            config = this.applyOverrides(config, overrides);
+        }
+        return config;
+    }
+}

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

@@ -0,0 +1,214 @@
+import type { AppwriteConfig } from "appwrite-utils";
+import { type ValidationError as BaseValidationError } from "../configValidation.js";
+/**
+ * Re-export types from configValidation for convenience
+ */
+export type ValidationError = BaseValidationError;
+/**
+ * Warning-level validation issue (non-blocking)
+ */
+export interface ValidationWarning extends BaseValidationError {
+    severity: "warning";
+}
+/**
+ * Complete validation result including errors, warnings, and suggestions
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    suggestions?: ValidationError[];
+}
+/**
+ * Options for validation reporting
+ */
+export interface ValidationReportOptions {
+    /**
+     * Include detailed information in the report
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Suppress console output (only log to file)
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * Exit process if validation fails
+     * @default false
+     */
+    exitOnError?: boolean;
+}
+/**
+ * Service for validating Appwrite configuration with support for multiple validation modes
+ *
+ * This service provides centralized configuration validation with:
+ * - Standard validation (warnings allowed)
+ * - Strict validation (warnings treated as errors)
+ * - Detailed error reporting with suggestions
+ * - Configurable output verbosity
+ *
+ * @example
+ * ```typescript
+ * const validationService = new ConfigValidationService();
+ *
+ * // Standard validation
+ * const result = validationService.validate(config);
+ * if (!result.isValid) {
+ *   validationService.reportResults(result, { verbose: true });
+ * }
+ *
+ * // Strict validation (warnings become errors)
+ * const strictResult = validationService.validateStrict(config);
+ * if (!strictResult.isValid) {
+ *   throw new Error("Configuration validation failed in strict mode");
+ * }
+ * ```
+ */
+export declare class ConfigValidationService {
+    /**
+     * Validate configuration with standard rules
+     *
+     * Standard validation allows warnings - the configuration is considered valid
+     * even if warnings are present. Only errors cause validation to fail.
+     *
+     * Validation checks include:
+     * - Basic structure validation (required fields, array structure)
+     * - Naming conflict detection (collections vs tables)
+     * - Database reference validation
+     * - Schema consistency validation
+     * - Duplicate definition detection
+     *
+     * @param config - Appwrite configuration to validate
+     * @returns Validation result with errors, warnings, and suggestions
+     *
+     * @example
+     * ```typescript
+     * const result = validationService.validate(config);
+     *
+     * if (result.isValid) {
+     *   console.log("Configuration is valid");
+     *   if (result.warnings.length > 0) {
+     *     console.log(`Found ${result.warnings.length} warnings`);
+     *   }
+     * } else {
+     *   console.error(`Configuration has ${result.errors.length} errors`);
+     * }
+     * ```
+     */
+    validate(config: AppwriteConfig): ValidationResult;
+    /**
+     * Validate configuration with strict rules
+     *
+     * Strict validation treats all warnings as errors. This is useful for:
+     * - CI/CD pipelines (fail builds on any issues)
+     * - Production deployments (ensure highest quality)
+     * - Configuration audits (enforce best practices)
+     *
+     * All warnings are promoted to errors, so the configuration is only
+     * considered valid if there are zero warnings and zero errors.
+     *
+     * @param config - Appwrite configuration to validate
+     * @returns Validation result with promoted warnings as errors
+     *
+     * @example
+     * ```typescript
+     * const result = validationService.validateStrict(config);
+     *
+     * if (!result.isValid) {
+     *   console.error("Configuration failed strict validation");
+     *   result.errors.forEach(err => {
+     *     console.error(`  - ${err.message}`);
+     *   });
+     *   process.exit(1);
+     * }
+     * ```
+     */
+    validateStrict(config: AppwriteConfig): ValidationResult;
+    /**
+     * Report validation results to console with formatted output
+     *
+     * Provides user-friendly formatting of validation results:
+     * - Color-coded output (errors in red, warnings in yellow, etc.)
+     * - Detailed error descriptions with suggestions
+     * - Affected items listing
+     * - Optional verbose mode for additional details
+     *
+     * @param validation - Validation result to report
+     * @param options - Reporting options (verbose, silent, exitOnError)
+     *
+     * @example
+     * ```typescript
+     * const result = validationService.validate(config);
+     *
+     * // Basic reporting
+     * validationService.reportResults(result);
+     *
+     * // Verbose reporting with all details
+     * validationService.reportResults(result, { verbose: true });
+     *
+     * // Report and exit on error (useful for scripts)
+     * validationService.reportResults(result, { exitOnError: true });
+     * ```
+     */
+    reportResults(validation: ValidationResult, options?: ValidationReportOptions): void;
+    /**
+     * Validate and report in a single call
+     *
+     * Convenience method that combines validation and reporting.
+     * Useful for quick validation checks in CLI commands.
+     *
+     * @param config - Appwrite configuration to validate
+     * @param strict - Use strict validation mode
+     * @param reportOptions - Reporting options
+     * @returns Validation result
+     *
+     * @example
+     * ```typescript
+     * // Quick validation with reporting
+     * const result = validationService.validateAndReport(config, false, {
+     *   verbose: true,
+     *   exitOnError: true
+     * });
+     * ```
+     */
+    validateAndReport(config: AppwriteConfig, strict?: boolean, reportOptions?: ValidationReportOptions): ValidationResult;
+    /**
+     * Check if configuration is valid without detailed reporting
+     *
+     * Quick validation check that returns a simple boolean.
+     * Useful for conditional logic where you don't need detailed error information.
+     *
+     * @param config - Appwrite configuration to validate
+     * @param strict - Use strict validation mode
+     * @returns true if configuration is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (validationService.isValid(config)) {
+     *   // Proceed with configuration
+     * } else {
+     *   // Show error and prompt for correction
+     * }
+     * ```
+     */
+    isValid(config: AppwriteConfig, strict?: boolean): boolean;
+    /**
+     * Get a summary of validation results as a formatted string
+     *
+     * Returns a human-readable summary of validation results suitable for
+     * logging or display in UIs.
+     *
+     * @param validation - Validation result to summarize
+     * @returns Formatted summary string
+     *
+     * @example
+     * ```typescript
+     * const result = validationService.validate(config);
+     * const summary = validationService.getSummary(result);
+     * console.log(summary);
+     * // Output: "Configuration valid with 2 warnings, 1 suggestion"
+     * ```
+     */
+    getSummary(validation: ValidationResult): string;
+}