appwrite-utils-cli 0.10.86 → 1.0.1

package/src/main.ts

@@ -7,12 +7,14 @@ import { UtilsController, type SetupOptions } from "./utilsController.js";
 import type { TransferOptions } from "./migrations/transfer.js";
 import { Databases, Storage, type Models } from "node-appwrite";
 import { getClient } from "./utils/getClientFromConfig.js";
-import { fetchAllDatabases } from "./migrations/databases.js";
+import { fetchAllDatabases } from "./databases/methods.js";
 import { setupDirsFiles } from "./utils/setupFiles.js";
 import { fetchAllCollections } from "./collections/methods.js";
 import type { Specification } from "appwrite-utils";
 import chalk from "chalk";
 import { listSpecifications } from "./functions/methods.js";
+import { MessageFormatter } from "./shared/messageFormatter.js";
+import { ConfirmationDialogs } from "./shared/confirmationDialogs.js";
 
 interface CliOptions {
   config?: string;
@@ -46,6 +48,7 @@ interface CliOptions {
   updateFunctionSpec?: boolean;
   functionId?: string;
   specification?: string;
+  migrateConfig?: boolean;
 }
 
 type ParsedArgv = ArgumentsCamelCase<CliOptions>;
@@ -53,21 +56,21 @@ type ParsedArgv = ArgumentsCamelCase<CliOptions>;
 const argv = yargs(hideBin(process.argv))
   .option("config", {
     type: "string",
-    description: "Appwrite Config file name",
+    description: "Path to Appwrite configuration file (appwriteConfig.ts)",
   })
   .option("it", {
     alias: ["interactive", "i"],
     type: "boolean",
-    description: "Run in interactive mode",
+    description: "Launch interactive CLI mode with guided prompts",
   })
   .option("dbIds", {
     type: "string",
-    description: "Comma-separated list of database IDs to operate on",
+    description: "Comma-separated list of database IDs to target (e.g., 'db1,db2,db3')",
   })
   .option("collectionIds", {
     alias: ["collIds"],
     type: "string",
-    description: "Comma-separated list of collection IDs to operate on",
+    description: "Comma-separated list of collection IDs to target (e.g., 'users,posts')",
   })
   .option("bucketIds", {
     type: "string",
@@ -76,12 +79,12 @@ const argv = yargs(hideBin(process.argv))
   .option("wipe", {
     choices: ["all", "docs", "users"] as const,
     description:
-      "Wipe data (all: everything, docs: only documents, users: only user data)",
+      "⚠️  DESTRUCTIVE: Wipe data (all: databases+storage+users, docs: documents only, users: user accounts only)",
   })
   .option("wipeCollections", {
     type: "boolean",
     description:
-      "Wipe collections, uses collectionIds option to get the collections to wipe",
+      "⚠️  DESTRUCTIVE: Wipe specific collections (requires --collectionIds)",
   })
   .option("transferUsers", {
     type: "boolean",
@@ -89,29 +92,29 @@ const argv = yargs(hideBin(process.argv))
   })
   .option("generate", {
     type: "boolean",
-    description: "Generate TypeScript schemas from database schemas",
+    description: "Generate TypeScript schemas and types from your Appwrite database schemas",
   })
   .option("import", {
     type: "boolean",
-    description: "Import data into your databases",
+    description: "Import data from importData/ directory into your Appwrite databases",
   })
   .option("backup", {
     type: "boolean",
-    description: "Perform a backup of your databases",
+    description: "Create a complete backup of your databases and collections",
   })
   .option("writeData", {
     type: "boolean",
-    description: "Write converted imported data to file",
+    description: "Output converted import data to files for validation before importing",
   })
   .option("push", {
     type: "boolean",
     description:
-      "Push your local Appwrite config to your configured Appwrite Project",
+      "Deploy your local configuration (collections, attributes, indexes) to Appwrite",
   })
   .option("sync", {
     type: "boolean",
     description:
-      "Synchronize by pulling your Appwrite config from your configured Appwrite Project",
+      "Pull and synchronize your local config with the remote Appwrite project schema",
   })
   .option("endpoint", {
     type: "string",
@@ -127,17 +130,17 @@ const argv = yargs(hideBin(process.argv))
   })
   .option("transfer", {
     type: "boolean",
-    description: "Transfer data between databases or collections",
+    description: "Transfer documents and files between databases, collections, or projects",
   })
   .option("fromDbId", {
     alias: ["fromDb", "sourceDbId", "sourceDb"],
     type: "string",
-    description: "Set the source database ID for transfer",
+    description: "Source database ID for transfer operations",
   })
   .option("toDbId", {
     alias: ["toDb", "targetDbId", "targetDb"],
     type: "string",
-    description: "Set the destination database ID for transfer",
+    description: "Target database ID for transfer operations",
   })
   .option("fromCollectionId", {
     alias: ["fromCollId", "fromColl"],
@@ -171,7 +174,7 @@ const argv = yargs(hideBin(process.argv))
   })
   .option("setup", {
     type: "boolean",
-    description: "Setup directories and files",
+    description: "Initialize project with configuration files and directory structure",
   })
   .option("updateFunctionSpec", {
     type: "boolean",
@@ -195,9 +198,17 @@ const argv = yargs(hideBin(process.argv))
       "s-8vcpu-8gb",
     ],
   })
+  .option("migrateConfig", {
+    alias: ["migrate"],
+    type: "boolean",
+    description: "Migrate appwriteConfig.ts to .appwrite structure with YAML configuration",
+  })
   .parse() as ParsedArgv;
 
 async function main() {
+  const startTime = Date.now();
+  const operationStats: Record<string, number> = {};
+  
   if (argv.it) {
     const cli = new InteractiveCLI(process.cwd());
     await cli.run();
@@ -218,8 +229,14 @@ async function main() {
       return;
     }
 
+    if (argv.migrateConfig) {
+      const { migrateConfig } = await import("./utils/configMigration.js");
+      await migrateConfig(process.cwd());
+      return;
+    }
+
     if (!controller.config) {
-      console.log(chalk.red("No Appwrite connection found"));
+      MessageFormatter.error("No Appwrite connection found", undefined, { prefix: "CLI" });
       return;
     }
 
@@ -248,10 +265,9 @@ async function main() {
           "Function ID and specification are required for updating function specs"
         );
       }
-      console.log(
-        chalk.yellow(
-          `Updating function specification for ${parsedArgv.functionId} to ${parsedArgv.specification}, checking if specification exists...`
-        )
+      MessageFormatter.info(
+        `Updating function specification for ${parsedArgv.functionId} to ${parsedArgv.specification}`,
+        { prefix: "Functions" }
       );
       const specifications = await listSpecifications(
         controller.appwriteServer!
@@ -261,8 +277,10 @@ async function main() {
           (s: { slug: string }) => s.slug === parsedArgv.specification
         )
       ) {
-        console.log(
-          chalk.red(`Specification ${parsedArgv.specification} not found`)
+        MessageFormatter.error(
+          `Specification ${parsedArgv.specification} not found`,
+          undefined,
+          { prefix: "Functions" }
         );
         return;
       }
@@ -276,7 +294,10 @@ async function main() {
     if (!options.databases || options.databases.length === 0) {
       const allDatabases = await fetchAllDatabases(controller.database!);
       options.databases = allDatabases.filter(
-        (db) => db.name.toLowerCase() !== "migrations"
+        (db) => {
+          const useMigrations = controller.config?.useMigrations ?? true;
+          return useMigrations || db.name.toLowerCase() !== "migrations";
+        }
       );
     }
 
@@ -290,9 +311,12 @@ async function main() {
     }
 
     if (options.doBackup && options.databases) {
+      MessageFormatter.info(`Creating backups for ${options.databases.length} database(s)`, { prefix: "Backup" });
       for (const db of options.databases) {
         await controller.backupDatabase(db);
       }
+      operationStats.backups = options.databases.length;
+      MessageFormatter.success(`Backup completed for ${options.databases.length} database(s)`, { prefix: "Backup" });
     }
 
     if (
@@ -301,26 +325,46 @@ async function main() {
       options.wipeUsers ||
       options.wipeCollections
     ) {
+      // Confirm destructive operations
+      const databaseNames = options.databases?.map(db => db.name) || [];
+      const confirmed = await ConfirmationDialogs.confirmDatabaseWipe(databaseNames, {
+        includeStorage: options.wipeDocumentStorage,
+        includeUsers: options.wipeUsers
+      });
+      
+      if (!confirmed) {
+        MessageFormatter.info("Operation cancelled by user", { prefix: "CLI" });
+        return;
+      }
+      
+      let wipeStats = { databases: 0, collections: 0, users: 0, buckets: 0 };
+      
       if (parsedArgv.wipe === "all") {
         if (options.databases) {
           for (const db of options.databases) {
             await controller.wipeDatabase(db, true); // true to wipe associated buckets
           }
+          wipeStats.databases = options.databases.length;
         }
         await controller.wipeUsers();
+        wipeStats.users = 1;
       } else if (parsedArgv.wipe === "docs") {
         if (options.databases) {
           for (const db of options.databases) {
             await controller.wipeBucketFromDatabase(db);
           }
+          wipeStats.databases = options.databases.length;
         }
         if (parsedArgv.bucketIds) {
-          for (const bucketId of parsedArgv.bucketIds.split(",")) {
+          const bucketIds = parsedArgv.bucketIds.split(",");
+          for (const bucketId of bucketIds) {
             await controller.wipeDocumentStorage(bucketId);
           }
+          wipeStats.buckets = bucketIds.length;
         }
       } else if (parsedArgv.wipe === "users") {
         await controller.wipeUsers();
+        wipeStats.users = 1;
       }
 
       // Handle specific collection wipes
@@ -333,11 +377,30 @@ async function main() {
           const collectionsToWipe = dbCollections.filter((c) =>
             options.collections!.includes(c.$id)
           );
-          for (const collection of collectionsToWipe) {
-            await controller.wipeCollection(db, collection);
+          
+          // Confirm collection wipe
+          const collectionNames = collectionsToWipe.map(c => c.name);
+          const collectionConfirmed = await ConfirmationDialogs.confirmCollectionWipe(
+            db.name,
+            collectionNames
+          );
+          
+          if (collectionConfirmed) {
+            for (const collection of collectionsToWipe) {
+              await controller.wipeCollection(db, collection);
+            }
+            wipeStats.collections += collectionsToWipe.length;
           }
         }
       }
+      
+      // Show wipe operation summary
+      if (wipeStats.databases > 0 || wipeStats.collections > 0 || wipeStats.users > 0 || wipeStats.buckets > 0) {
+        operationStats.wipedDatabases = wipeStats.databases;
+        operationStats.wipedCollections = wipeStats.collections;
+        operationStats.wipedUsers = wipeStats.users;
+        operationStats.wipedBuckets = wipeStats.buckets;
+      }
     }
 
     if (parsedArgv.push || parsedArgv.sync) {
@@ -359,17 +422,22 @@ async function main() {
 
       if (parsedArgv.push) {
         await controller.syncDb(databases, collections);
+        operationStats.pushedDatabases = databases.length;
+        operationStats.pushedCollections = collections.length;
       } else if (parsedArgv.sync) {
         await controller.synchronizeConfigurations(databases);
+        operationStats.syncedDatabases = databases.length;
       }
     }
 
     if (options.generateSchemas) {
       await controller.generateSchemas();
+      operationStats.generatedSchemas = 1;
     }
 
     if (options.importData) {
       await controller.importData(options);
+      operationStats.importCompleted = 1;
     }
 
     if (parsedArgv.transfer) {
@@ -380,16 +448,15 @@ async function main() {
 
       // Only fetch databases if database IDs are provided
       if (parsedArgv.fromDbId && parsedArgv.toDbId) {
-        console.log(
-          chalk.blue(
-            `Starting database transfer from ${parsedArgv.fromDbId} to ${parsedArgv.toDbId}`
-          )
+        MessageFormatter.info(
+          `Starting database transfer from ${parsedArgv.fromDbId} to ${parsedArgv.toDbId}`,
+          { prefix: "Transfer" }
         );
         fromDb = (
           await controller.getDatabasesByIds([parsedArgv.fromDbId])
         )?.[0];
         if (!fromDb) {
-          console.log(chalk.red("Source database not found"));
+          MessageFormatter.error("Source database not found", undefined, { prefix: "Transfer" });
           return;
         }
         if (isRemote) {
@@ -410,19 +477,19 @@ async function main() {
           const remoteDbs = await fetchAllDatabases(targetDatabases);
           toDb = remoteDbs.find((db) => db.$id === parsedArgv.toDbId);
           if (!toDb) {
-            console.log(chalk.red("Target database not found"));
+            MessageFormatter.error("Target database not found", undefined, { prefix: "Transfer" });
             return;
           }
         } else {
           toDb = (await controller.getDatabasesByIds([parsedArgv.toDbId]))?.[0];
           if (!toDb) {
-            console.log(chalk.red("Target database not found"));
+            MessageFormatter.error("Target database not found", undefined, { prefix: "Transfer" });
             return;
           }
         }
 
         if (!fromDb || !toDb) {
-          console.log(chalk.red("Source or target database not found"));
+          MessageFormatter.error("Source or target database not found", undefined, { prefix: "Transfer" });
           return;
         }
       }
@@ -470,11 +537,18 @@ async function main() {
       };
 
       await controller.transferData(transferOptions);
+      operationStats.transfers = 1;
+    }
+    
+    // Show final operation summary if any operations were performed
+    if (Object.keys(operationStats).length > 0) {
+      const duration = Date.now() - startTime;
+      MessageFormatter.operationSummary("CLI Operations", operationStats, duration);
     }
   }
 }
 
 main().catch((error) => {
-  console.error("An error occurred:", error);
+  MessageFormatter.error("CLI execution failed", error, { prefix: "CLI" });
   process.exit(1);
 });

package/src/migrations/afterImportActions.ts

@@ -11,7 +11,7 @@ import { InputFile } from "node-appwrite/file";
 import path from "path";
 import fs from "fs";
 import os from "os";
-import { logger } from "./logging.js";
+import { logger } from "../shared/logging.js";
 import {
   tryAwaitWithRetry,
   type AfterImportActions,
@@ -485,7 +485,7 @@ export const afterImportActions = {
         // Use arrayBuffer if buffer is not available
         const arrayBuffer = await response.arrayBuffer();
         const buffer = Buffer.from(arrayBuffer);
-        fs.writeFileSync(tempFilePath, buffer);
+        fs.writeFileSync(tempFilePath, new Uint8Array(buffer));
 
         // Create InputFile from the downloaded file
         const inputFile = InputFile.fromPath(tempFilePath, fileName);

package/src/migrations/appwriteToX.ts

@@ -1,4 +1,5 @@
-import { SchemaGenerator } from "./schemaStrings.js";
+import { SchemaGenerator } from "../shared/schemaGenerator.js";
+import { findYamlConfig } from "../config/yamlConfig.js";
 import {
   Client,
   Compression,
@@ -9,7 +10,7 @@ import {
   type Permission,
 } from "node-appwrite";
 import { fetchAllCollections } from "../collections/methods.js";
-import { fetchAllDatabases } from "./databases.js";
+import { fetchAllDatabases } from "../databases/methods.js";
 import {
   CollectionSchema,
   attributeSchema,
@@ -92,7 +93,7 @@ export class AppwriteToX {
 
     // Loop through each database
     for (const database of databases) {
-      if (database.name.toLowerCase() === "migrations") {
+      if (!this.config.useMigrations && database.name.toLowerCase() === "migrations") {
         continue;
       }
 
@@ -274,7 +275,19 @@ export class AppwriteToX {
       this.updatedConfig,
       this.appwriteFolderPath
     );
-    generator.updateTsSchemas();
+
+    // Check if this is a YAML-based project
+    const yamlConfigPath = findYamlConfig(this.appwriteFolderPath);
+    const isYamlProject = !!yamlConfigPath;
+
+    if (isYamlProject) {
+      console.log("📄 Detected YAML configuration - generating YAML collection definitions");
+      generator.updateYamlCollections();
+    } else {
+      console.log("📝 Generating TypeScript collection definitions");
+      generator.updateTsSchemas();
+    }
+    
     generator.generateSchemas();
   }
 }

package/src/migrations/dataLoader.ts

@@ -14,14 +14,14 @@ import {
 } from "appwrite-utils";
 import path from "path";
 import fs from "fs";
-import { convertObjectByAttributeMappings } from "./converters.js";
+import { convertObjectByAttributeMappings } from "../utils/dataConverters.js";
 import { z } from "zod";
 import { checkForCollection } from "../collections/methods.js";
 import { ID, Users, type Databases } from "node-appwrite";
-import { logger } from "./logging.js";
-import { findOrCreateOperation, updateOperation } from "./migrationHelper.js";
+import { logger } from "../shared/logging.js";
+import { findOrCreateOperation, updateOperation } from "../shared/migrationHelpers.js";
 import { AuthUserCreateSchema } from "../schemas/authUser.js";
-import { UsersController } from "./users.js";
+import { UsersController } from "../users/methods.js";
 import { finalizeByAttributeMap } from "../utils/helperFunctions.js";
 import { isEmpty } from "es-toolkit/compat";
 

package/src/migrations/importController.ts

@@ -16,19 +16,21 @@ import type { ImportDataActions } from "./importDataActions.js";
 import { areCollectionNamesSame, tryAwaitWithRetry } from "../utils/index.js";
 import type { SetupOptions } from "../utilsController.js";
 import { resolveAndUpdateRelationships } from "./relationships.js";
-import { UsersController } from "./users.js";
-import { logger } from "./logging.js";
-import { updateOperation } from "./migrationHelper.js";
+import { UsersController } from "../users/methods.js";
+import { logger } from "../shared/logging.js";
+import { updateOperation } from "../shared/migrationHelpers.js";
 import {
   BatchSchema,
   OperationCreateSchema,
   OperationSchema,
-} from "./backup.js";
+} from "../storage/schemas.js";
 import { DataLoader, type CollectionImportData } from "./dataLoader.js";
 import {
   transferDatabaseLocalToLocal,
   transferStorageLocalToLocal,
 } from "./transfer.js";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+import { ProgressManager } from "../shared/progressManager.js";
 
 export class ImportController {
   private config: AppwriteConfig;
@@ -82,13 +84,11 @@ export class ImportController {
     let databaseRan: Models.Database | undefined;
 
     for (let db of databasesToProcess) {
-      if (db.name.toLowerCase().trim().replace(" ", "") === "migrations") {
+      if (!this.config.useMigrations && db.name.toLowerCase().trim().replace(" ", "") === "migrations") {
         continue;
       }
 
-      console.log(`---------------------------------`);
-      console.log(`Starting import data for database: ${db.name}`);
-      console.log(`---------------------------------`);
+      MessageFormatter.banner(`Starting import data for database: ${db.name}`, "Database Import");
 
       if (!databaseRan) {
         databaseRan = db;
@@ -286,14 +286,18 @@ export class ImportController {
           continue;
         }
 
-        const importOperation = await this.database.getDocument(
-          "migrations",
-          "currentOperations",
-          importOperationId
-        );
-        await updateOperation(this.database, importOperation.$id, {
-          status: "in_progress",
-        });
+        let importOperation: any = null;
+        if (this.config.useMigrations) {
+          importOperation = await this.database.getDocument(
+            "migrations",
+            "currentOperations",
+            importOperationId
+          );
+          await updateOperation(this.database, importOperation.$id, {
+            status: "in_progress",
+          }, this.config.useMigrations);
+        }
+        
         const collectionData = dataLoader.importMap.get(
           dataLoader.getCollectionKey(collection.name)
         );
@@ -344,14 +348,18 @@ export class ImportController {
           // Wait for all promises in the current batch to resolve
           await Promise.all(batchPromises);
           console.log(`Completed batch ${i + 1} of ${dataSplit.length}`);
-          await updateOperation(this.database, importOperation.$id, {
-            progress: processedItems,
-          });
+          if (this.config.useMigrations && importOperation) {
+            await updateOperation(this.database, importOperation.$id, {
+              progress: processedItems,
+            }, this.config.useMigrations);
+          }
         }
         // After all batches are processed, update the operation status to completed
-        await updateOperation(this.database, importOperation.$id, {
-          status: "completed",
-        });
+        if (this.config.useMigrations && importOperation) {
+          await updateOperation(this.database, importOperation.$id, {
+            status: "completed",
+          }, this.config.useMigrations);
+        }
       }
     }
   }

package/src/migrations/importDataActions.ts

@@ -6,10 +6,10 @@ import {
   type AttributeMappings,
 } from "appwrite-utils";
 import { converterFunctions, type ConverterFunctions } from "appwrite-utils";
-import { convertObjectBySchema } from "./converters.js";
+import { convertObjectBySchema } from "../utils/dataConverters.js";
 import { type AfterImportActions } from "appwrite-utils";
 import { afterImportActions } from "./afterImportActions.js";
-import { logger } from "./logging.js";
+import { logger } from "../shared/logging.js";
 import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
 
 export class ImportDataActions {

package/src/migrations/relationships.ts

@@ -5,7 +5,7 @@ import type {
   Attribute,
   RelationshipAttribute,
 } from "appwrite-utils";
-import { logger } from "./logging.js";
+import { logger } from "../shared/logging.js";
 
 /**
  * Finds collections that have defined relationship attributes.