appwrite-utils-cli 1.5.2 → 1.6.1

package/dist/utilsController.js

@@ -5,16 +5,18 @@ import { UsersController } from "./users/methods.js";
 import { AppwriteToX } from "./migrations/appwriteToX.js";
 import { ImportController } from "./migrations/importController.js";
 import { ImportDataActions } from "./migrations/importDataActions.js";
-import { setupMigrationDatabase, ensureDatabasesExist, wipeOtherDatabases, ensureCollectionsExist, } from "./databases/setup.js";
+import { ensureDatabasesExist, wipeOtherDatabases, ensureCollectionsExist, } from "./databases/setup.js";
 import { createOrUpdateCollections, wipeDatabase, generateSchemas, fetchAllCollections, wipeCollection, } from "./collections/methods.js";
 import { wipeAllTables, wipeTableRows } from "./collections/methods.js";
-import { backupDatabase, ensureDatabaseConfigBucketsExist, initOrGetBackupStorage, wipeDocumentStorage, } from "./storage/methods.js";
+import { backupDatabase, ensureDatabaseConfigBucketsExist, wipeDocumentStorage, } from "./storage/methods.js";
 import path from "path";
 import { converterFunctions, validationRules, } from "appwrite-utils";
 import { afterImportActions } from "./migrations/afterImportActions.js";
 import { transferDatabaseLocalToLocal, transferDatabaseLocalToRemote, transferStorageLocalToLocal, transferStorageLocalToRemote, transferUsersLocalToRemote, } from "./migrations/transfer.js";
-import { getClient } from "./utils/getClientFromConfig.js";
+import { getClient, getClientWithAuth } from "./utils/getClientFromConfig.js";
 import { getAdapterFromConfig } from "./utils/getClientFromConfig.js";
+import { hasSessionAuth, findSessionByEndpointAndProject, isValidSessionCookie } from "./utils/sessionAuth.js";
+import { createSessionPreservation } from "./utils/loadConfigs.js";
 import { fetchAllDatabases } from "./databases/methods.js";
 import { listFunctions, updateFunctionSpecifications, } from "./functions/methods.js";
 import chalk from "chalk";
@@ -24,6 +26,7 @@ import { configureLogging, updateLogger } from "./shared/logging.js";
 import { MessageFormatter, Messages } from "./shared/messageFormatter.js";
 import { SchemaGenerator } from "./shared/schemaGenerator.js";
 import { findYamlConfig } from "./config/yamlConfig.js";
+import { validateCollectionsTablesConfig, reportValidationResults, validateWithStrictMode } from "./config/configValidation.js";
 export class UtilsController {
     appwriteFolderPath;
     appwriteConfigPath;
@@ -31,9 +34,14 @@ export class UtilsController {
     appwriteServer;
     database;
     storage;
+    adapter;
     converterDefinitions = converterFunctions;
     validityRuleDefinitions = validationRules;
     afterImportActionsDefinitions = afterImportActions;
+    // Session preservation fields
+    sessionCookie;
+    authMethod;
+    sessionMetadata;
     constructor(currentUserDir, directConfig) {
         const basePath = currentUserDir;
         if (directConfig) {
@@ -46,19 +54,29 @@ export class UtilsController {
                 MessageFormatter.error("Appwrite project is required", undefined, { prefix: "Config" });
                 hasErrors = true;
             }
-            if (!directConfig.appwriteKey) {
-                MessageFormatter.error("Appwrite key is required", undefined, { prefix: "Config" });
+            // Check authentication: either API key or session auth is required
+            const hasValidSession = directConfig.appwriteEndpoint && directConfig.appwriteProject &&
+                hasSessionAuth(directConfig.appwriteEndpoint, directConfig.appwriteProject);
+            if (!directConfig.appwriteKey && !hasValidSession) {
+                MessageFormatter.error("Authentication required: provide an API key or login with 'appwrite login'", undefined, { prefix: "Config" });
                 hasErrors = true;
             }
+            else if (!directConfig.appwriteKey && hasValidSession) {
+                MessageFormatter.info("Using session authentication (no API key required)", { prefix: "Auth" });
+            }
+            else if (directConfig.appwriteKey && hasValidSession) {
+                MessageFormatter.info("API key provided, session authentication also available", { prefix: "Auth" });
+            }
             if (!hasErrors) {
                 // Only set config if we have all required fields
                 this.appwriteFolderPath = basePath;
                 this.config = {
                     appwriteEndpoint: directConfig.appwriteEndpoint,
                     appwriteProject: directConfig.appwriteProject,
-                    appwriteKey: directConfig.appwriteKey,
+                    appwriteKey: directConfig.appwriteKey || "",
                     appwriteClient: null,
                     apiMode: "auto", // Default to auto-detect for dual API support
+                    authMethod: "auto", // Default to auto-detect authentication method
                     enableBackups: false,
                     backupInterval: 0,
                     backupRetention: 0,
@@ -66,7 +84,6 @@ export class UtilsController {
                     enableMockData: false,
                     documentBucketId: "",
                     usersCollectionName: "",
-                    useMigrations: true,
                     databases: [],
                     buckets: [],
                     functions: [],
@@ -89,17 +106,26 @@ export class UtilsController {
             this.appwriteFolderPath = appwriteConfigFound; // For YAML configs, findAppwriteConfig already returns the correct directory
         }
     }
-    async init() {
+    async init(options = {}) {
+        const { validate = false, strictMode = false, useSession = false, sessionCookie } = options;
         if (!this.config) {
             if (this.appwriteFolderPath && this.appwriteConfigPath) {
                 MessageFormatter.progress("Loading config from file...", { prefix: "Config" });
                 try {
-                    const { config, actualConfigPath } = await loadConfigWithPath(this.appwriteFolderPath);
+                    const { config, actualConfigPath, validation } = await loadConfigWithPath(this.appwriteFolderPath, { validate, strictMode, reportValidation: false });
                     this.config = config;
                     MessageFormatter.info(`Loaded config from: ${actualConfigPath}`, { prefix: "Config" });
+                    // Report validation results if validation was requested
+                    if (validation && validate) {
+                        reportValidationResults(validation, { verbose: false });
+                        // In strict mode, throw if validation fails
+                        if (strictMode && !validation.isValid) {
+                            throw new Error(`Configuration validation failed in strict mode. Found ${validation.errors.length} validation errors.`);
+                        }
+                    }
                 }
                 catch (error) {
-                    MessageFormatter.error("Failed to load config from file", undefined, { prefix: "Config" });
+                    MessageFormatter.error("Failed to load config from file", error instanceof Error ? error : undefined, { prefix: "Config" });
                     return;
                 }
             }
@@ -113,23 +139,39 @@ export class UtilsController {
             configureLogging(this.config.logging);
             updateLogger();
         }
-        this.appwriteServer = new Client();
-        this.appwriteServer
-            .setEndpoint(this.config.appwriteEndpoint)
-            .setProject(this.config.appwriteProject)
-            .setKey(this.config.appwriteKey);
+        // Use enhanced client with session authentication support
+        // Pass session cookie from options if provided
+        const clientSessionCookie = sessionCookie || this.sessionCookie;
+        this.appwriteServer = getClientWithAuth(this.config.appwriteEndpoint, this.config.appwriteProject, this.config.appwriteKey || undefined, clientSessionCookie);
         this.database = new Databases(this.appwriteServer);
         this.storage = new Storage(this.appwriteServer);
         this.config.appwriteClient = this.appwriteServer;
+        // Initialize adapter with version detection
+        try {
+            const { adapter, apiMode } = await getAdapterFromConfig(this.config, false, clientSessionCookie);
+            this.adapter = adapter;
+            MessageFormatter.info(`Database adapter initialized (apiMode: ${apiMode})`, {
+                prefix: "Adapter"
+            });
+        }
+        catch (error) {
+            MessageFormatter.warning('Database adapter initialization failed - some features may not work', { prefix: "Adapter" });
+        }
+        // Extract and store session information after successful authentication
+        this.extractSessionInfo();
     }
     async reloadConfig() {
         if (!this.appwriteFolderPath) {
             MessageFormatter.error("Failed to get appwriteFolderPath", undefined, { prefix: "Controller" });
             return;
         }
-        this.config = await loadConfig(this.appwriteFolderPath);
+        // Preserve session authentication during config reload
+        const preserveAuth = this.createSessionPreservationOptions();
+        this.config = await loadConfig(this.appwriteFolderPath, {
+            preserveAuth
+        });
         if (!this.config) {
-            console.log(chalk.red("Failed to load config"));
+            MessageFormatter.error("Failed to load config", undefined, { prefix: "Controller" });
             return;
         }
         // Configure logging based on updated config
@@ -137,22 +179,24 @@ export class UtilsController {
             configureLogging(this.config.logging);
             updateLogger();
         }
-        this.appwriteServer = new Client();
-        this.appwriteServer
-            .setEndpoint(this.config.appwriteEndpoint)
-            .setProject(this.config.appwriteProject)
-            .setKey(this.config.appwriteKey);
+        // Use enhanced client with session authentication support, passing preserved session
+        this.appwriteServer = getClientWithAuth(this.config.appwriteEndpoint, this.config.appwriteProject, this.config.appwriteKey || undefined, this.sessionCookie);
         this.database = new Databases(this.appwriteServer);
         this.storage = new Storage(this.appwriteServer);
         this.config.appwriteClient = this.appwriteServer;
-    }
-    async setupMigrationDatabase() {
-        await this.init();
-        if (!this.config) {
-            MessageFormatter.error("Config not initialized", undefined, { prefix: "Controller" });
-            return;
+        // Re-initialize adapter with version detection after config reload
+        try {
+            const { adapter, apiMode } = await getAdapterFromConfig(this.config, false, this.sessionCookie);
+            this.adapter = adapter;
+            MessageFormatter.info(`Database adapter re-initialized (apiMode: ${apiMode})`, {
+                prefix: "Adapter"
+            });
         }
-        await setupMigrationDatabase(this.config);
+        catch (error) {
+            MessageFormatter.warning('Database adapter re-initialization failed - some features may not work', { prefix: "Adapter" });
+        }
+        // Re-extract session information after reload
+        this.extractSessionInfo();
     }
     async ensureDatabaseConfigBucketsExist(databases = []) {
         await this.init();
@@ -172,7 +216,6 @@ export class UtilsController {
             MessageFormatter.error("Config not initialized", undefined, { prefix: "Controller" });
             return;
         }
-        await this.setupMigrationDatabase();
         await this.ensureDatabaseConfigBucketsExist(databases);
         await ensureDatabasesExist(this.config, databases);
     }
@@ -204,29 +247,29 @@ export class UtilsController {
             MessageFormatter.error("Database not initialized", undefined, { prefix: "Controller" });
             return;
         }
-        await wipeOtherDatabases(this.database, databasesToKeep, this.config?.useMigrations ?? true);
+        await wipeOtherDatabases(this.database, databasesToKeep);
     }
     async wipeUsers() {
         await this.init();
         if (!this.config || !this.database) {
-            console.log(chalk.red("Config or database not initialized"));
+            MessageFormatter.error("Config or database not initialized", undefined, { prefix: "Controller" });
             return;
         }
         const usersController = new UsersController(this.config, this.database);
         await usersController.wipeUsers();
     }
-    async backupDatabase(database) {
+    async backupDatabase(database, format = 'json') {
         await this.init();
         if (!this.database || !this.storage || !this.config) {
-            console.log(chalk.red("Database, storage, or config not initialized"));
+            MessageFormatter.error("Database, storage, or config not initialized", undefined, { prefix: "Controller" });
             return;
         }
-        await backupDatabase(this.config, this.database, database.$id, this.storage);
+        await backupDatabase(this.config, this.database, database.$id, this.storage, format);
     }
     async listAllFunctions() {
         await this.init();
         if (!this.appwriteServer) {
-            console.log(chalk.red("Appwrite server not initialized"));
+            MessageFormatter.error("Appwrite server not initialized", undefined, { prefix: "Controller" });
             return [];
         }
         const { functions } = await listFunctions(this.appwriteServer, [
@@ -241,7 +284,7 @@ export class UtilsController {
         }
         const functionsDir = findFunctionsDir(this.appwriteFolderPath);
         if (!functionsDir) {
-            console.log(chalk.red("Failed to find functions directory"));
+            MessageFormatter.error("Failed to find functions directory", undefined, { prefix: "Controller" });
             return new Map();
         }
         const functionDirMap = new Map();
@@ -263,14 +306,14 @@ export class UtilsController {
     async deployFunction(functionName, functionPath, functionConfig) {
         await this.init();
         if (!this.appwriteServer) {
-            console.log(chalk.red("Appwrite server not initialized"));
+            MessageFormatter.error("Appwrite server not initialized", undefined, { prefix: "Controller" });
             return;
         }
         if (!functionConfig) {
             functionConfig = this.config?.functions?.find((f) => f.name === functionName);
         }
         if (!functionConfig) {
-            console.log(chalk.red(`Function ${functionName} not found in config`));
+            MessageFormatter.error(`Function ${functionName} not found in config`, undefined, { prefix: "Controller" });
             return;
         }
         await deployLocalFunction(this.appwriteServer, functionName, functionConfig, functionPath);
@@ -278,7 +321,7 @@ export class UtilsController {
     async syncFunctions() {
         await this.init();
         if (!this.appwriteServer) {
-            console.log(chalk.red("Appwrite server not initialized"));
+            MessageFormatter.error("Appwrite server not initialized", undefined, { prefix: "Controller" });
             return;
         }
         const localFunctions = this.config?.functions || [];
@@ -296,7 +339,7 @@ export class UtilsController {
         if (!this.database || !this.config)
             throw new Error("Database not initialized");
         try {
-            const { adapter, apiMode } = await getAdapterFromConfig(this.config);
+            const { adapter, apiMode } = await getAdapterFromConfig(this.config, false, this.sessionCookie);
             if (apiMode === 'tablesdb') {
                 await wipeAllTables(adapter, database.$id);
             }
@@ -339,7 +382,7 @@ export class UtilsController {
         if (!this.database || !this.config)
             throw new Error("Database not initialized");
         try {
-            const { adapter, apiMode } = await getAdapterFromConfig(this.config);
+            const { adapter, apiMode } = await getAdapterFromConfig(this.config, false, this.sessionCookie);
             if (apiMode === 'tablesdb') {
                 await wipeTableRows(adapter, database.$id, collection.$id);
             }
@@ -362,8 +405,6 @@ export class UtilsController {
         if (!this.database || !this.config)
             throw new Error("Database or config not initialized");
         for (const database of databases) {
-            if (!this.config.useMigrations && database.$id === "migrations")
-                continue;
             await this.createOrUpdateCollections(database, undefined, collections);
         }
     }
@@ -374,10 +415,24 @@ export class UtilsController {
         await createOrUpdateCollections(this.database, database.$id, this.config, deletedCollections, collections);
     }
     async generateSchemas() {
-        await this.init();
+        // Schema generation doesn't need Appwrite connection, just config
         if (!this.config) {
-            MessageFormatter.error("Config not initialized", undefined, { prefix: "Controller" });
-            return;
+            if (this.appwriteFolderPath && this.appwriteConfigPath) {
+                MessageFormatter.progress("Loading config from file...", { prefix: "Config" });
+                try {
+                    const { config, actualConfigPath } = await loadConfigWithPath(this.appwriteFolderPath, { validate: false, strictMode: false, reportValidation: false });
+                    this.config = config;
+                    MessageFormatter.info(`Loaded config from: ${actualConfigPath}`, { prefix: "Config" });
+                }
+                catch (error) {
+                    MessageFormatter.error("Failed to load config from file", error instanceof Error ? error : undefined, { prefix: "Config" });
+                    return;
+                }
+            }
+            else {
+                MessageFormatter.error("No configuration available", undefined, { prefix: "Controller" });
+                return;
+            }
         }
         if (!this.appwriteFolderPath) {
             MessageFormatter.error("Failed to get appwriteFolderPath", undefined, { prefix: "Controller" });
@@ -442,12 +497,10 @@ export class UtilsController {
             const allDatabases = await fetchAllDatabases(this.database);
             databases = allDatabases;
         }
-        // Ensure DBs exist (this may internally ensure migrations exists)
+        // Ensure DBs exist
         await this.ensureDatabasesExist(databases);
         await this.ensureDatabaseConfigBucketsExist(databases);
-        // Do not push collections to the migrations database (prevents duplicate runs)
-        const dbsForCollections = databases.filter((db) => (this.config?.useMigrations ?? true) ? db.name.toLowerCase() !== "migrations" : true);
-        await this.createOrUpdateCollectionsForDatabases(dbsForCollections, collections);
+        await this.createOrUpdateCollectionsForDatabases(databases, collections);
     }
     getAppwriteFolderPath() {
         return this.appwriteFolderPath;
@@ -458,14 +511,14 @@ export class UtilsController {
         let sourceDatabases = [];
         let targetDatabases = [];
         if (!sourceClient) {
-            console.log(chalk.red("Source database not initialized"));
+            MessageFormatter.error("Source database not initialized", undefined, { prefix: "Controller" });
             return;
         }
         if (options.isRemote) {
             if (!options.transferEndpoint ||
                 !options.transferProject ||
                 !options.transferKey) {
-                console.log(chalk.red("Remote transfer options are missing"));
+                MessageFormatter.error("Remote transfer options are missing", undefined, { prefix: "Controller" });
                 return;
             }
             const remoteClient = getClient(options.transferEndpoint, options.transferProject, options.transferKey);
@@ -482,7 +535,7 @@ export class UtilsController {
             const fromDb = sourceDatabases.find((db) => db.$id === options.fromDb.$id);
             const targetDb = targetDatabases.find((db) => db.$id === options.targetDb.$id);
             if (!fromDb || !targetDb) {
-                console.log(chalk.red("Source or target database not found"));
+                MessageFormatter.error("Source or target database not found", undefined, { prefix: "Controller" });
                 return;
             }
             if (options.isRemote && targetClient) {
@@ -494,10 +547,10 @@ export class UtilsController {
         }
         if (options.transferUsers) {
             if (!options.isRemote) {
-                console.log(chalk.yellow("User transfer is only supported for remote transfers. Skipping..."));
+                MessageFormatter.warning("User transfer is only supported for remote transfers. Skipping...", { prefix: "Controller" });
             }
             else if (!this.appwriteServer) {
-                console.log(chalk.red("Appwrite server not initialized"));
+                MessageFormatter.error("Appwrite server not initialized", undefined, { prefix: "Controller" });
                 return;
             }
             else {
@@ -543,4 +596,81 @@ export class UtilsController {
         await updateFunctionSpecifications(this.appwriteServer, functionId, specification);
         MessageFormatter.success(`Successfully updated function specifications for ${functionId} to ${specification}`, { prefix: "Functions" });
     }
+    /**
+     * Validates the current configuration for collections/tables conflicts
+     */
+    async validateConfiguration(strictMode = false) {
+        await this.init();
+        if (!this.config) {
+            throw new Error("Configuration not loaded");
+        }
+        MessageFormatter.progress("Validating configuration...", { prefix: "Validation" });
+        const validation = strictMode
+            ? validateWithStrictMode(this.config, strictMode)
+            : validateCollectionsTablesConfig(this.config);
+        reportValidationResults(validation, { verbose: true });
+        if (validation.isValid) {
+            MessageFormatter.success("Configuration validation passed", { prefix: "Validation" });
+        }
+        else {
+            MessageFormatter.error(`Configuration validation failed with ${validation.errors.length} errors`, undefined, { prefix: "Validation" });
+        }
+        return validation;
+    }
+    /**
+     * Extract session information from the current authenticated client
+     * This preserves session context for use across config reloads and adapter operations
+     */
+    extractSessionInfo() {
+        if (!this.config) {
+            return;
+        }
+        // Try to extract session from current config first
+        if (this.config.sessionCookie && isValidSessionCookie(this.config.sessionCookie)) {
+            this.sessionCookie = this.config.sessionCookie;
+            this.authMethod = "session";
+            this.sessionMetadata = this.config.sessionMetadata;
+            MessageFormatter.debug("Extracted session from config", { prefix: "Session" });
+            return;
+        }
+        // Fall back to finding session from Appwrite CLI preferences
+        const sessionAuth = findSessionByEndpointAndProject(this.config.appwriteEndpoint, this.config.appwriteProject);
+        if (sessionAuth && isValidSessionCookie(sessionAuth.sessionCookie)) {
+            this.sessionCookie = sessionAuth.sessionCookie;
+            this.authMethod = "session";
+            this.sessionMetadata = {
+                email: sessionAuth.email
+            };
+            MessageFormatter.debug(`Extracted session from CLI preferences for ${sessionAuth.email || 'unknown user'}`, { prefix: "Session" });
+            return;
+        }
+        // No session found, using API key authentication
+        if (this.config.appwriteKey) {
+            this.authMethod = "apikey";
+            this.sessionCookie = undefined;
+            this.sessionMetadata = undefined;
+            MessageFormatter.debug("Using API key authentication", { prefix: "Session" });
+        }
+    }
+    /**
+     * Create session preservation options for passing to loadConfig
+     * Returns current session state to maintain authentication across config reloads
+     */
+    createSessionPreservationOptions() {
+        if (!this.sessionCookie || !isValidSessionCookie(this.sessionCookie)) {
+            return undefined;
+        }
+        return createSessionPreservation(this.sessionCookie, this.sessionMetadata?.email, this.sessionMetadata?.expiresAt);
+    }
+    /**
+     * Get current session information for debugging/logging purposes
+     */
+    getSessionInfo() {
+        return {
+            hasSession: !!this.sessionCookie && isValidSessionCookie(this.sessionCookie),
+            authMethod: this.authMethod,
+            email: this.sessionMetadata?.email,
+            expiresAt: this.sessionMetadata?.expiresAt
+        };
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "main": "src/main.ts",
   "type": "module",
   "repository": {
@@ -27,13 +27,17 @@
     "build": "bun run tsc",
     "start": "tsx --no-cache src/main.ts",
     "deploy": "bun run build && npm publish --access public",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:ci": "jest --ci --coverage --watchAll=false",
     "postinstall": "echo 'This package is intended for CLI use only and should not be added as a dependency in other projects.'"
   },
   "dependencies": {
     "@types/inquirer": "^9.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/yargs": "^17.0.33",
-    "appwrite-utils": "^1.4.1",
+    "appwrite-utils": "^1.6.1",
     "chalk": "^5.4.1",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
@@ -41,6 +45,7 @@
     "ignore": "^6.0.2",
     "inquirer": "^9.3.7",
     "js-yaml": "^4.1.0",
+    "jszip": "^3.10.1",
     "luxon": "^3.6.1",
     "nanostores": "^0.10.3",
     "node-appwrite": "^17",
@@ -54,10 +59,15 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@jest/globals": "^29.7.0",
     "@types/cli-progress": "^3.11.6",
+    "@types/jest": "^29.5.12",
     "@types/js-yaml": "^4.0.9",
+    "@types/jszip": "^3.4.1",
     "@types/lodash": "^4.17.18",
     "@types/luxon": "^3.6.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
     "typescript": "^5.8.3"
   }
 }