appwrite-utils-cli 1.6.2 → 1.6.4

package/src/config/services/__tests__/ConfigMergeService.test.ts

@@ -0,0 +1,351 @@
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { ConfigMergeService } from "../ConfigMergeService.js";
+import type { ConfigOverrides } from "../ConfigMergeService.js";
+import type { AppwriteConfig } from "appwrite-utils";
+import type { SessionAuthInfo } from "../SessionAuthService.js";
+
+describe("ConfigMergeService", () => {
+  let service: ConfigMergeService;
+  let baseConfig: AppwriteConfig;
+  let sessionInfo: SessionAuthInfo;
+
+  // Store original env vars
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    service = new ConfigMergeService();
+
+    baseConfig = {
+      appwriteEndpoint: "https://cloud.appwrite.io/v1",
+      appwriteProject: "test-project",
+      appwriteKey: "test-api-key",
+      databases: [],
+      buckets: [],
+      functions: [],
+    } as unknown as AppwriteConfig;
+
+    sessionInfo = {
+      projectId: "test-project",
+      endpoint: "https://cloud.appwrite.io/v1",
+      cookie: "eyJhbGc.test.cookie",
+      email: "test@example.com",
+    };
+  });
+
+  afterEach(() => {
+    // Restore original env vars
+    process.env = { ...originalEnv };
+  });
+
+  describe("mergeSession", () => {
+    it("should merge session cookie into config", () => {
+      const result = service.mergeSession(baseConfig, sessionInfo);
+
+      expect(result.sessionCookie).toBe("eyJhbGc.test.cookie");
+      expect(result.authMethod).toBe("session");
+    });
+
+    it("should not mutate original config", () => {
+      const original = { ...baseConfig };
+      service.mergeSession(baseConfig, sessionInfo);
+
+      expect(baseConfig).toEqual(original);
+    });
+
+    it("should preserve all existing config properties", () => {
+      const result = service.mergeSession(baseConfig, sessionInfo);
+
+      expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+      expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+      expect(result.appwriteKey).toBe(baseConfig.appwriteKey);
+    });
+  });
+
+  describe("applyOverrides", () => {
+    it("should apply all provided overrides", () => {
+      const overrides: ConfigOverrides = {
+        appwriteEndpoint: "https://custom.appwrite.io/v1",
+        appwriteProject: "override-project",
+        appwriteKey: "override-key",
+        sessionCookie: "override-cookie",
+        authMethod: "apikey",
+      };
+
+      const result = service.applyOverrides(baseConfig, overrides);
+
+      expect(result.appwriteEndpoint).toBe("https://custom.appwrite.io/v1");
+      expect(result.appwriteProject).toBe("override-project");
+      expect(result.appwriteKey).toBe("override-key");
+      expect(result.sessionCookie).toBe("override-cookie");
+      expect(result.authMethod).toBe("apikey");
+    });
+
+    it("should skip undefined and null values", () => {
+      const overrides: ConfigOverrides = {
+        appwriteEndpoint: undefined,
+        appwriteProject: null as any,
+        appwriteKey: "new-key",
+      };
+
+      const result = service.applyOverrides(baseConfig, overrides);
+
+      expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+      expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+      expect(result.appwriteKey).toBe("new-key");
+    });
+
+    it("should not mutate original config", () => {
+      const original = { ...baseConfig };
+      const overrides: ConfigOverrides = {
+        appwriteEndpoint: "https://custom.appwrite.io/v1",
+      };
+
+      service.applyOverrides(baseConfig, overrides);
+
+      expect(baseConfig).toEqual(original);
+    });
+  });
+
+  describe("mergeEnvironmentVariables", () => {
+    it("should merge environment variables when config values are not set", () => {
+      process.env.APPWRITE_ENDPOINT = "https://env.appwrite.io/v1";
+      process.env.APPWRITE_PROJECT = "env-project";
+      process.env.APPWRITE_API_KEY = "env-api-key";
+      process.env.APPWRITE_SESSION_COOKIE = "env-cookie";
+
+      const emptyConfig = {
+        databases: [],
+        buckets: [],
+        functions: [],
+      } as unknown as AppwriteConfig;
+
+      const result = service.mergeEnvironmentVariables(emptyConfig);
+
+      expect(result.appwriteEndpoint).toBe("https://env.appwrite.io/v1");
+      expect(result.appwriteProject).toBe("env-project");
+      expect(result.appwriteKey).toBe("env-api-key");
+      expect(result.sessionCookie).toBe("env-cookie");
+    });
+
+    it("should not override existing config values", () => {
+      process.env.APPWRITE_ENDPOINT = "https://env.appwrite.io/v1";
+      process.env.APPWRITE_PROJECT = "env-project";
+
+      const result = service.mergeEnvironmentVariables(baseConfig);
+
+      expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+      expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+    });
+
+    it("should ignore empty environment variables", () => {
+      process.env.APPWRITE_ENDPOINT = "";
+      process.env.APPWRITE_PROJECT = "";
+
+      const emptyConfig = {
+        databases: [],
+        buckets: [],
+        functions: [],
+      } as unknown as AppwriteConfig;
+
+      const result = service.mergeEnvironmentVariables(emptyConfig);
+
+      expect(result.appwriteEndpoint).toBeUndefined();
+      expect(result.appwriteProject).toBeUndefined();
+    });
+  });
+
+  describe("mergeSources", () => {
+    it("should merge multiple sources in priority order", () => {
+      const source1 = {
+        appwriteEndpoint: "https://source1.appwrite.io/v1",
+        appwriteProject: "source1-project",
+      };
+
+      const source2 = {
+        appwriteProject: "source2-project",
+        appwriteKey: "source2-key",
+      };
+
+      const source3 = {
+        appwriteKey: "source3-key",
+        sessionCookie: "source3-cookie",
+      };
+
+      const result = service.mergeSources([source1, source2, source3]);
+
+      expect(result.appwriteEndpoint).toBe("https://source1.appwrite.io/v1");
+      expect(result.appwriteProject).toBe("source2-project");
+      expect(result.appwriteKey).toBe("source3-key");
+      expect(result.sessionCookie).toBe("source3-cookie");
+    });
+
+    it("should handle arrays by replacing, not merging", () => {
+      const source1 = {
+        appwriteEndpoint: "https://cloud.appwrite.io/v1",
+        appwriteProject: "test",
+        databases: [{ $id: "db1", name: "db1" }],
+      } as Partial<AppwriteConfig>;
+
+      const source2 = {
+        databases: [{ $id: "db2", name: "db2" }, { $id: "db3", name: "db3" }],
+      } as Partial<AppwriteConfig>;
+
+      const result = service.mergeSources([source1, source2]);
+
+      expect(result.databases).toHaveLength(2);
+      expect(result.databases).toEqual([{ $id: "db2", name: "db2" }, { $id: "db3", name: "db3" }]);
+    });
+
+    it("should skip undefined and null sources", () => {
+      const source1 = {
+        appwriteEndpoint: "https://cloud.appwrite.io/v1",
+        appwriteProject: "test",
+      };
+
+      const result = service.mergeSources([
+        source1,
+        undefined as any,
+        null as any,
+        { appwriteKey: "key" },
+      ]);
+
+      expect(result.appwriteEndpoint).toBe("https://cloud.appwrite.io/v1");
+      expect(result.appwriteProject).toBe("test");
+      expect(result.appwriteKey).toBe("key");
+    });
+
+    it("should throw error when no valid sources provided", () => {
+      expect(() => service.mergeSources([])).toThrow(
+        "No valid configuration sources provided for merging"
+      );
+
+      expect(() =>
+        service.mergeSources([undefined as any, null as any])
+      ).toThrow("No valid configuration sources provided for merging");
+    });
+
+    it("should throw error when merged config lacks required fields", () => {
+      const invalidSource = {
+        appwriteKey: "key",
+      };
+
+      expect(() => service.mergeSources([invalidSource])).toThrow(
+        "Merged configuration is missing required fields"
+      );
+    });
+  });
+
+  describe("mergeAllSources", () => {
+    it("should merge all sources in correct priority order", () => {
+      process.env.APPWRITE_ENDPOINT = "https://env.appwrite.io/v1";
+      process.env.APPWRITE_API_KEY = "env-key";
+
+      const overrides: ConfigOverrides = {
+        appwriteKey: "override-key",
+      };
+
+      const result = service.mergeAllSources(baseConfig, {
+        session: sessionInfo,
+        overrides,
+        includeEnv: true,
+      });
+
+      // Base config endpoint
+      expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+      // Session should set session cookie
+      expect(result.sessionCookie).toBe(sessionInfo.cookie);
+      // Override should win for API key
+      expect(result.appwriteKey).toBe("override-key");
+    });
+
+    it("should exclude environment variables when includeEnv is false", () => {
+      process.env.APPWRITE_SESSION_COOKIE = "env-cookie";
+
+      const configWithoutKey = {
+        ...baseConfig,
+        appwriteKey: undefined,
+      } as unknown as AppwriteConfig;
+
+      const result = service.mergeAllSources(configWithoutKey, {
+        includeEnv: false,
+      });
+
+      expect(result.sessionCookie).toBeUndefined();
+    });
+
+    it("should work with only base config", () => {
+      const result = service.mergeAllSources(baseConfig, {});
+
+      expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+      expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+    });
+
+    it("should apply priority: overrides > session > env > base", () => {
+      process.env.APPWRITE_KEY = "env-key";
+
+      const configWithoutKey = {
+        ...baseConfig,
+        appwriteKey: undefined,
+        sessionCookie: undefined,
+      } as unknown as AppwriteConfig;
+
+      // Test with session (should override env)
+      const withSession = service.mergeAllSources(configWithoutKey, {
+        session: sessionInfo,
+        includeEnv: true,
+      });
+
+      expect(withSession.sessionCookie).toBe(sessionInfo.cookie);
+      expect(withSession.authMethod).toBe("session");
+
+      // Test with override (should override session)
+      const withOverride = service.mergeAllSources(configWithoutKey, {
+        session: sessionInfo,
+        overrides: { authMethod: "apikey" },
+        includeEnv: true,
+      });
+
+      expect(withOverride.authMethod).toBe("apikey");
+    });
+  });
+
+  describe("deep merge behavior", () => {
+    it("should deeply merge nested objects", () => {
+      const source1 = {
+        appwriteEndpoint: "https://cloud.appwrite.io/v1",
+        appwriteProject: "test",
+        databases: [
+          {
+            $id: "db1",
+            name: "Database 1",
+          },
+        ],
+      } as Partial<AppwriteConfig>;
+
+      const source2 = {
+        databases: [
+          {
+            $id: "db1",
+            name: "Updated Database",
+          },
+        ],
+      } as Partial<AppwriteConfig>;
+
+      const result = service.mergeSources([source1, source2]);
+
+      // Arrays are replaced, not merged
+      expect(result.databases).toHaveLength(1);
+      expect(result.databases![0].name).toBe("Updated Database");
+    });
+
+    it("should preserve immutability throughout merge chain", () => {
+      const original1 = { ...baseConfig };
+      const original2 = { appwriteKey: "new-key" };
+
+      service.mergeSources([baseConfig, original2]);
+
+      expect(baseConfig).toEqual(original1);
+      expect(original2).toEqual({ appwriteKey: "new-key" });
+    });
+  });
+});

package/src/config/services/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration Services
+ *
+ * Modular services for configuration management, discovery, loading, validation, and merging.
+ */
+
+export { ConfigDiscoveryService } from "./ConfigDiscoveryService.js";
+export type { DiscoveryResult } from "./ConfigDiscoveryService.js";
+
+export { ConfigLoaderService } from "./ConfigLoaderService.js";
+export type { CollectionLoadOptions } from "./ConfigLoaderService.js";
+
+export { ConfigMergeService } from "./ConfigMergeService.js";
+export type { ConfigOverrides } from "./ConfigMergeService.js";
+
+export {
+  SessionAuthService,
+  type SessionAuthInfo,
+  type AppwriteSessionPrefs,
+  type AuthenticationStatus
+} from "./SessionAuthService.js";
+
+export {
+  ConfigValidationService,
+  type ValidationResult,
+  type ValidationError,
+  type ValidationWarning,
+  type ValidationReportOptions
+} from "./ConfigValidationService.js";

package/src/interactiveCLI.ts

@@ -196,11 +196,11 @@ export class InteractiveCLI {
     appwriteKey: string;
   }): Promise<void> {
     if (!this.controller) {
-      this.controller = new UtilsController(this.currentDir, directConfig);
+      this.controller = UtilsController.getInstance(this.currentDir, directConfig);
       await this.controller.init();
     } else {
       // Extract session info from existing controller before reinitializing
-      const sessionInfo = this.controller.getSessionInfo();
+      const sessionInfo = await this.controller.getSessionInfo();
       if (sessionInfo.hasSession && directConfig) {
         // Create enhanced directConfig with session preservation
         const enhancedDirectConfig = {
@@ -210,11 +210,13 @@ export class InteractiveCLI {
         };
 
         // Reinitialize with session preservation
-        this.controller = new UtilsController(this.currentDir, enhancedDirectConfig);
+        UtilsController.clearInstance();
+        this.controller = UtilsController.getInstance(this.currentDir, enhancedDirectConfig);
         await this.controller.init();
       } else if (directConfig) {
         // Standard reinitialize without session
-        this.controller = new UtilsController(this.currentDir, directConfig);
+        UtilsController.clearInstance();
+        this.controller = UtilsController.getInstance(this.currentDir, directConfig);
         await this.controller.init();
       }
       // If no directConfig provided, keep existing controller
@@ -985,18 +987,18 @@ export class InteractiveCLI {
   /**
    * Extract session information from current controller for preservation
    */
-  private extractSessionFromController(): {
+  private async extractSessionFromController(): Promise<{
     appwriteEndpoint: string;
     appwriteProject: string;
     appwriteKey?: string;
     sessionCookie?: string;
     sessionMetadata?: any;
-  } | undefined {
+  } | undefined> {
     if (!this.controller?.config) {
       return undefined;
     }
 
-    const sessionInfo = this.controller.getSessionInfo();
+    const sessionInfo = await this.controller.getSessionInfo();
     const config = this.controller.config;
 
     if (!config.appwriteEndpoint || !config.appwriteProject) {

package/src/main.ts

@@ -424,8 +424,8 @@ async function main() {
       }
     }
 
-    // Create controller with session authentication support
-    const controller = new UtilsController(process.cwd(), finalDirectConfig);
+    // Create controller with session authentication support using singleton
+    const controller = UtilsController.getInstance(process.cwd(), finalDirectConfig);
 
     // Pass session authentication options to the controller
     const initOptions: any = {};

package/src/shared/operationQueue.ts

@@ -76,7 +76,7 @@ export const clearProcessingState = () => {
   processedAttributes.clear();
   nameToIdMapping.clear();
 
-  MessageFormatter.success("Cleared processing state caches");
+  logger.debug("Cleared processing state caches", { operation: "clearProcessingState", sizeBefore });
   logger.info('Processing state cleared', {
     sizeBefore,
     operation: 'clearProcessingState'

package/src/utils/ClientFactory.ts

@@ -0,0 +1,186 @@
+import { Client } from "node-appwrite";
+import type { AppwriteConfig } from "appwrite-utils";
+import { AdapterFactory } from "../adapters/AdapterFactory.js";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { logger } from "../shared/logging.js";
+
+/**
+ * Factory for creating authenticated Appwrite clients and database adapters.
+ *
+ * This factory provides a clean separation of concerns by taking pre-configured
+ * AppwriteConfig objects (with authentication already resolved by ConfigManager)
+ * and creating the necessary client and adapter instances.
+ *
+ * Key features:
+ * - Takes pre-authenticated config from ConfigManager
+ * - Creates client with appropriate authentication method
+ * - Creates adapter with automatic version detection
+ * - Leverages AdapterFactory's internal caching for performance
+ *
+ * @example
+ * ```typescript
+ * const configManager = ConfigManager.getInstance();
+ * const config = await configManager.loadConfig();
+ *
+ * // Config already has session or API key resolved
+ * const { client, adapter } = await ClientFactory.createFromConfig(config);
+ * ```
+ */
+export class ClientFactory {
+  /**
+   * Create authenticated client and database adapter from configuration.
+   *
+   * This method expects the config to have authentication already resolved:
+   * - Either `sessionCookie` is set (from ConfigManager's session loading)
+   * - Or `appwriteKey` is set (from config file or CLI overrides)
+   *
+   * The ConfigManager handles all session discovery and authentication priority,
+   * so this factory simply applies the resolved authentication to the client.
+   *
+   * @param config - AppwriteConfig with resolved authentication
+   * @returns Object containing authenticated client and database adapter
+   * @throws Error if no authentication method is available in config
+   *
+   * @example
+   * ```typescript
+   * const config = await ConfigManager.getInstance().loadConfig();
+   * const { client, adapter } = await ClientFactory.createFromConfig(config);
+   *
+   * // Client is now authenticated and ready to use
+   * const databases = new Databases(client);
+   * const collections = await adapter.listCollections(databaseId);
+   * ```
+   */
+  public static async createFromConfig(
+    config: AppwriteConfig
+  ): Promise<{ client: Client; adapter: DatabaseAdapter }> {
+    logger.debug("Creating client from config", {
+      prefix: "ClientFactory",
+      hasSession: !!config.sessionCookie,
+      hasApiKey: !!config.appwriteKey,
+      endpoint: config.appwriteEndpoint,
+      project: config.appwriteProject,
+    });
+
+    // Create base client with endpoint and project
+    const client = new Client()
+      .setEndpoint(config.appwriteEndpoint)
+      .setProject(config.appwriteProject);
+
+    // Apply authentication (priority already resolved by ConfigManager)
+    if (config.sessionCookie) {
+      // Session authentication (from ConfigManager's session loading)
+      client.setSession(config.sessionCookie);
+      logger.debug("Applied session authentication to client", {
+        prefix: "ClientFactory",
+        email: config.sessionMetadata?.email,
+      });
+    } else if (config.appwriteKey) {
+      // API key authentication (from config file or overrides)
+      client.setKey(config.appwriteKey);
+      logger.debug("Applied API key authentication to client", {
+        prefix: "ClientFactory",
+      });
+    } else {
+      // No authentication available - this should have been caught by ConfigManager
+      const error = new Error(
+        "No authentication method available in configuration.\n\n" +
+        "This should have been resolved by ConfigManager during config loading.\n" +
+        "Expected either:\n" +
+        "  - config.sessionCookie (from session authentication)\n" +
+        "  - config.appwriteKey (from config file or CLI overrides)\n\n" +
+        "Suggestion: Ensure ConfigManager.loadConfig() was called before ClientFactory.createFromConfig()."
+      );
+      logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
+      throw error;
+    }
+
+    // Create adapter with version detection
+    // AdapterFactory uses internal caching, so repeated calls are fast
+    logger.debug("Creating database adapter", {
+      prefix: "ClientFactory",
+      apiMode: config.apiMode || "auto",
+    });
+
+    const { adapter } = await AdapterFactory.createFromConfig(config);
+
+    logger.debug("Client and adapter created successfully", {
+      prefix: "ClientFactory",
+      adapterType: adapter.getApiMode(),
+    });
+
+    return { client, adapter };
+  }
+
+  /**
+   * Create client and adapter from individual parameters.
+   *
+   * This is a lower-level method for cases where you don't have a full
+   * AppwriteConfig object. For most use cases, prefer createFromConfig().
+   *
+   * @param endpoint - Appwrite endpoint URL
+   * @param project - Appwrite project ID
+   * @param options - Authentication and API mode options
+   * @returns Object containing authenticated client and database adapter
+   * @throws Error if no authentication method is provided
+   *
+   * @example
+   * ```typescript
+   * const { client, adapter } = await ClientFactory.create(
+   *   "https://cloud.appwrite.io/v1",
+   *   "my-project-id",
+   *   {
+   *     apiKey: "my-api-key",
+   *     apiMode: "auto"
+   *   }
+   * );
+   * ```
+   */
+  public static async create(
+    endpoint: string,
+    project: string,
+    options: {
+      apiKey?: string;
+      sessionCookie?: string;
+      apiMode?: "auto" | "legacy" | "tablesdb";
+    } = {}
+  ): Promise<{ client: Client; adapter: DatabaseAdapter }> {
+    logger.debug("Creating client from parameters", {
+      prefix: "ClientFactory",
+      hasSession: !!options.sessionCookie,
+      hasApiKey: !!options.apiKey,
+      endpoint,
+      project,
+    });
+
+    // Create minimal config object
+    const config: AppwriteConfig = {
+      appwriteEndpoint: endpoint,
+      appwriteProject: project,
+      appwriteKey: options.apiKey || "",
+      sessionCookie: options.sessionCookie,
+      apiMode: options.apiMode || "auto",
+      // Minimal required fields
+      appwriteClient: null,
+      authMethod: options.sessionCookie ? "session" : "apikey",
+      enableBackups: false,
+      backupInterval: 0,
+      backupRetention: 0,
+      enableBackupCleanup: false,
+      enableMockData: false,
+      documentBucketId: "",
+      usersCollectionName: "",
+      databases: [],
+      buckets: [],
+      functions: [],
+      logging: {
+        enabled: false,
+        level: "info",
+        console: false,
+      },
+    };
+
+    // Use main createFromConfig method
+    return this.createFromConfig(config);
+  }
+}

package/src/utils/getClientFromConfig.ts

@@ -4,6 +4,7 @@ import { AdapterFactory, type AdapterFactoryResult } from "../adapters/AdapterFa
 import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
 import { findSessionByEndpointAndProject, hasSessionAuth, isValidSessionCookie } from "./sessionAuth.js";
 import { MessageFormatter } from "../shared/messageFormatter.js";
+import { logger } from "../shared/logging.js";
 
 /**
  * Enhanced client creation from config with session authentication support
@@ -43,7 +44,7 @@ export const getClientWithAuth = (
   if (sessionCookie) {
     if (isValidSessionCookie(sessionCookie)) {
       client.setSession(sessionCookie);
-      MessageFormatter.info(`Using explicit session authentication for project ${project}`, { prefix: "Auth" });
+      logger.debug("Using explicit session authentication", { prefix: "Auth", project });
       return client;
     } else {
       authAttempts.push("explicit session cookie (invalid format)");
@@ -56,7 +57,7 @@ export const getClientWithAuth = (
   if (sessionAuth) {
     if (isValidSessionCookie(sessionAuth.sessionCookie)) {
       client.setSession(sessionAuth.sessionCookie);
-      MessageFormatter.info(`Using session authentication for project ${project} (${sessionAuth.email || 'unknown user'})`, { prefix: "Auth" });
+      logger.debug("Using session authentication", { prefix: "Auth", project, email: sessionAuth.email || 'unknown user' });
       return client;
     } else {
       authAttempts.push("session from CLI prefs (invalid/expired)");
@@ -70,7 +71,7 @@ export const getClientWithAuth = (
       authAttempts.push("API key (empty)");
     } else {
       client.setKey(key);
-      MessageFormatter.info(`Using API key authentication for project ${project}`, { prefix: "Auth" });
+      logger.debug("Using API key authentication", { prefix: "Auth", project });
       return client;
     }
   }