appwrite-utils-cli 1.5.1 → 1.6.0

package/src/setupController.ts

@@ -3,6 +3,7 @@ import { loadConfig } from "./utils/loadConfigs.js";
 import path from "path";
 import fs from "fs";
 import type { AppwriteConfig } from "appwrite-utils";
+import { MessageFormatter } from "./shared/messageFormatter.js";
 
 export class SetupController {
   private currentDir: string;
@@ -14,7 +15,7 @@ export class SetupController {
 
   async runSetup(withExampleData: boolean = false): Promise<void> {
     await setupDirsFiles(withExampleData, this.currentDir);
-    console.log("Setup completed successfully.");
+    MessageFormatter.success("Setup completed successfully", { prefix: "Setup" });
   }
 
   async loadConfig(): Promise<AppwriteConfig | null> {
@@ -24,7 +25,7 @@ export class SetupController {
         this.config = await loadConfig(appwriteDir);
         return this.config;
       } catch (error) {
-        console.error("Error loading config:", error);
+        MessageFormatter.error("Error loading config", error as Error, { prefix: "Setup" });
         return null;
       }
     }

package/src/shared/backupMetadataSchema.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+
+/**
+ * Schema for centralized backup tracking table (_appwrite_backups)
+ *
+ * Tracks all backups created for databases, buckets, and comprehensive backups
+ */
+
+export type BackupType = 'database' | 'bucket' | 'comprehensive';
+export type BackupFormat = 'json' | 'zip';
+export type BackupStatus = 'completed' | 'partial' | 'failed';
+export type RestorationStatus = 'completed' | 'partial' | 'failed' | 'not_restored';
+
+export const BACKUP_TYPES = ['database', 'bucket', 'comprehensive'] as const;
+export const BACKUP_FORMATS = ['json', 'zip'] as const;
+export const BACKUP_STATUSES = ['completed', 'partial', 'failed'] as const;
+export const RESTORATION_STATUSES = ['completed', 'partial', 'failed', 'not_restored'] as const;
+
+export const BackupTypeSchema = z.enum(['database', 'bucket', 'comprehensive']);
+export const BackupFormatSchema = z.enum(['json', 'zip']);
+export const BackupStatusSchema = z.enum(['completed', 'partial', 'failed']);
+export const RestorationStatusSchema = z.enum(['completed', 'partial', 'failed', 'not_restored']);
+
+export interface BackupMetadata {
+  $id: string;
+  $createdAt: string;
+  $updatedAt: string;
+
+  // Core backup info
+  backupType: BackupType;         // Type of backup: database, bucket, or comprehensive
+  backupId: string;               // File ID in storage bucket for the backup file
+  manifestFileId?: string;        // File ID for the manifest JSON file
+  format: BackupFormat;           // 'json' or 'zip'
+  sizeBytes: number;              // Total backup file size
+
+  // Resource identification (at least one must be present)
+  databaseId?: string;            // Database ID (for database backups)
+  bucketId?: string;              // Bucket ID (for bucket backups)
+  comprehensiveBackupId?: string; // Parent comprehensive backup ID
+
+  // Database-specific metrics
+  collections?: number;           // Number of collections backed up
+  documents?: number;             // Number of documents backed up
+
+  // Bucket-specific metrics
+  fileCount?: number;             // Number of files backed up (for bucket backups)
+
+  // Status tracking
+  status: BackupStatus;           // 'completed', 'partial', or 'failed'
+  error?: string;                 // Error message if failed or partial
+
+  // Restoration tracking
+  restoredAt?: string;            // ISO timestamp of restoration
+  restorationStatus: RestorationStatus; // Restoration status
+  restorationError?: string;      // Error message if restoration failed
+}
+
+export const BackupMetadataSchema = z.object({
+  $id: z.string(),
+  $createdAt: z.string(),
+  $updatedAt: z.string(),
+
+  // Core backup info
+  backupType: BackupTypeSchema,
+  backupId: z.string(),
+  manifestFileId: z.string().optional(),
+  format: BackupFormatSchema,
+  sizeBytes: z.number(),
+
+  // Resource identification
+  databaseId: z.string().optional(),
+  bucketId: z.string().optional(),
+  comprehensiveBackupId: z.string().optional(),
+
+  // Database-specific metrics
+  collections: z.number().optional(),
+  documents: z.number().optional(),
+
+  // Bucket-specific metrics
+  fileCount: z.number().optional(),
+
+  // Status tracking
+  status: BackupStatusSchema,
+  error: z.string().optional(),
+
+  // Restoration tracking
+  restoredAt: z.string().optional(),
+  restorationStatus: RestorationStatusSchema.default('not_restored'),
+  restorationError: z.string().optional()
+});
+
+export const BACKUP_TABLE_ID = "appwrite_backups";
+export const BACKUP_TABLE_NAME = "Backup Tracking";

package/src/shared/backupTracking.ts

@@ -0,0 +1,211 @@
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { logger } from "./logging.js";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import {
+  BACKUP_TABLE_ID,
+  BACKUP_TABLE_NAME,
+  type BackupMetadata,
+  BackupMetadataSchema
+} from "./backupMetadataSchema.js";
+
+/**
+ * Checks if backup tracking table exists in database
+ */
+async function tableExists(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<boolean> {
+  try {
+    await db.getTable({ databaseId, tableId: BACKUP_TABLE_ID });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Creates the backup tracking table in the specified database
+ */
+export async function createBackupTrackingTable(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<void> {
+  // Check if table already exists
+  const exists = await tableExists(db, databaseId);
+  if (exists) {
+    logger.debug("Backup tracking table already exists", {
+      databaseId,
+      tableId: BACKUP_TABLE_ID
+    });
+    return;
+  }
+
+  logger.info("Creating backup tracking table", {
+    databaseId,
+    tableId: BACKUP_TABLE_ID
+  });
+
+  // Create table
+  await tryAwaitWithRetry(async () => {
+    await db.createTable({
+      databaseId,
+      id: BACKUP_TABLE_ID,
+      name: BACKUP_TABLE_NAME
+    });
+  });
+
+  // Create attributes
+  const attributes = [
+    {
+      key: "backupId",
+      type: "string" as const,
+      size: 50,
+      required: true
+    },
+    {
+      key: "databaseId",
+      type: "string" as const,
+      size: 50,
+      required: true
+    },
+    {
+      key: "sizeBytes",
+      type: "integer" as const,
+      required: true
+    },
+    {
+      key: "collections",
+      type: "integer" as const,
+      required: true
+    },
+    {
+      key: "documents",
+      type: "integer" as const,
+      required: true
+    },
+    {
+      key: "format",
+      type: "enum" as const,
+      elements: ["json", "zip"],
+      required: true
+    },
+    {
+      key: "status",
+      type: "enum" as const,
+      elements: ["completed", "failed"],
+      required: true
+    },
+    {
+      key: "error",
+      type: "string" as const,
+      size: 10000,
+      required: false
+    }
+  ];
+
+  for (const attr of attributes) {
+    await tryAwaitWithRetry(async () => {
+      await db.createAttribute({
+        databaseId,
+        tableId: BACKUP_TABLE_ID,
+        ...attr
+      });
+    });
+  }
+
+  logger.info("Backup tracking table created successfully", {
+    databaseId,
+    tableId: BACKUP_TABLE_ID
+  });
+}
+
+/**
+ * Records backup metadata in the tracking table
+ */
+export async function recordBackup(
+  db: DatabaseAdapter,
+  databaseId: string,
+  metadata: Omit<BackupMetadata, '$id' | '$createdAt' | '$updatedAt'>
+): Promise<BackupMetadata> {
+  // Ensure tracking table exists
+  await createBackupTrackingTable(db, databaseId);
+
+  // Create backup record
+  const result = await db.createRow({
+    databaseId,
+    tableId: BACKUP_TABLE_ID,
+    id: ID.unique(),
+    data: {
+      backupId: metadata.backupId,
+      databaseId: metadata.databaseId,
+      sizeBytes: metadata.sizeBytes,
+      collections: metadata.collections,
+      documents: metadata.documents,
+      format: metadata.format,
+      status: metadata.status,
+      error: metadata.error
+    }
+  });
+
+  logger.info("Recorded backup metadata", {
+    backupId: metadata.backupId,
+    databaseId: metadata.databaseId,
+    format: metadata.format
+  });
+
+  return result.data as BackupMetadata;
+}
+
+/**
+ * Lists all backups for a database, sorted by creation date (newest first)
+ */
+export async function listBackups(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<BackupMetadata[]> {
+  try {
+    const result = await db.listRows({
+      databaseId,
+      tableId: BACKUP_TABLE_ID,
+      queries: [
+        Query.orderDesc("$createdAt"),
+        Query.limit(100) // Limit to last 100 backups
+      ]
+    });
+
+    return (result.rows || []) as BackupMetadata[];
+  } catch (error) {
+    // Table might not exist yet
+    logger.debug("No backup tracking table found", { databaseId });
+    return [];
+  }
+}
+
+/**
+ * Gets the most recent backup for a database
+ */
+export async function getLastBackup(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<BackupMetadata | null> {
+  try {
+    const result = await db.listRows({
+      databaseId,
+      tableId: BACKUP_TABLE_ID,
+      queries: [
+        Query.orderDesc("$createdAt"),
+        Query.limit(1)
+      ]
+    });
+
+    if (result.rows && result.rows.length > 0) {
+      return result.rows[0] as BackupMetadata;
+    }
+
+    return null;
+  } catch (error) {
+    logger.debug("No backup found or table doesn't exist", { databaseId });
+    return null;
+  }
+}

package/src/shared/confirmationDialogs.ts

@@ -27,18 +27,18 @@ export class ConfirmationDialogs {
       return true;
     }
 
-    MessageFormatter.warning(`You are about to perform a destructive operation:`);
-    console.log(chalk.red.bold(`  Operation: ${options.operation}`));
-    console.log(chalk.yellow(`  Targets: ${options.targets.join(", ")}`));
-    
+    MessageFormatter.warning(`You are about to perform a destructive operation:`, { skipLogging: true });
+    MessageFormatter.error(`Operation: ${options.operation}`, undefined, { skipLogging: true });
+    MessageFormatter.warning(`Targets: ${options.targets.join(", ")}`, { skipLogging: true });
+
     if (options.consequences && options.consequences.length > 0) {
-      console.log(chalk.red("\n  This will:"));
+      MessageFormatter.error("This will:", undefined, { skipLogging: true });
       options.consequences.forEach(consequence => {
-        console.log(chalk.red(`    • ${consequence}`));
+        MessageFormatter.error(`  • ${consequence}`, undefined, { skipLogging: true });
       });
     }
 
-    console.log(chalk.red("\n  ⚠️  THIS ACTION CANNOT BE UNDONE!"));
+    MessageFormatter.error("⚠️  THIS ACTION CANNOT BE UNDONE!", undefined, { skipLogging: true });
 
     if (options.requireExplicitConfirmation && options.confirmationText) {
       const { confirmation } = await inquirer.prompt([{
@@ -68,12 +68,12 @@ export class ConfirmationDialogs {
    * Prompts user about creating a backup before a destructive operation
    */
   static async promptForBackup(options: BackupPromptOptions): Promise<'yes' | 'no' | 'skip'> {
-    const message = options.backupMessage || 
+    const message = options.backupMessage ||
       `Create a backup before performing ${options.operation} on: ${options.targets.join(", ")}?`;
 
-    console.log(chalk.blue("\n🛡️  Backup Recommendation"));
+    MessageFormatter.info("🛡️  Backup Recommendation", { skipLogging: true });
     if (options.recommendBackup !== false) {
-      console.log(chalk.yellow("  It's strongly recommended to create a backup before proceeding."));
+      MessageFormatter.warning("It's strongly recommended to create a backup before proceeding.", { skipLogging: true });
     }
     
     const { choice } = await inquirer.prompt([{
@@ -95,12 +95,12 @@ export class ConfirmationDialogs {
    * Shows a final confirmation before proceeding with an operation
    */
   static async finalConfirmation(operation: string, details?: string[]): Promise<boolean> {
-    console.log(chalk.green(`\n✅ Ready to perform: ${chalk.bold(operation)}`));
-    
+    MessageFormatter.success(`Ready to perform: ${operation}`, { skipLogging: true });
+
     if (details && details.length > 0) {
-      console.log(chalk.gray("   Details:"));
+      MessageFormatter.debug("Details:", undefined, { skipLogging: true });
       details.forEach(detail => {
-        console.log(chalk.gray(`     • ${detail}`));
+        MessageFormatter.debug(`  • ${detail}`, undefined, { skipLogging: true });
       });
     }
 
@@ -215,19 +215,19 @@ export class ConfirmationDialogs {
     
     Object.entries(summary).forEach(([key, value]) => {
       const formattedKey = key.replace(/([A-Z])/g, ' $1').replace(/^./, str => str.toUpperCase());
-      
+
       if (Array.isArray(value)) {
-        console.log(`${chalk.gray("●")} ${formattedKey}:`);
+        MessageFormatter.info(`● ${formattedKey}:`, { skipLogging: true });
         value.forEach(item => {
-          console.log(`  ${chalk.gray("•")} ${item}`);
+          MessageFormatter.debug(`  • ${item}`, undefined, { skipLogging: true });
         });
       } else {
-        console.log(`${chalk.gray("●")} ${formattedKey}: ${chalk.cyan(String(value))}`);
+        MessageFormatter.info(`● ${formattedKey}: ${String(value)}`, { skipLogging: true });
       }
     });
 
     if (options.warningMessage) {
-      console.log(chalk.yellow(`\n⚠️  ${options.warningMessage}`));
+      MessageFormatter.warning(`⚠️  ${options.warningMessage}`, { skipLogging: true });
     }
 
     if (options.confirmationRequired !== false) {

package/src/shared/errorUtils.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared error handling utilities for consistent error processing
+ */
+
+/**
+ * Extracts error message from unknown error type
+ * @param error - Error of unknown type
+ * @returns String error message
+ */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Normalizes unknown error to Error instance
+ * @param error - Error of unknown type
+ * @returns Normalized Error object
+ */
+export function normalizeError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Checks if error is a conflict error (409)
+ * @param error - Error object to check
+ * @returns True if error is a conflict (duplicate resource)
+ */
+export function isConflictError(error: any): boolean {
+  return error?.code === 409 || (error?.message?.toLowerCase().includes('already exists') ?? false);
+}
+
+/**
+ * Checks if error is a Cloudflare error (522)
+ * @param error - Error object to check
+ * @returns True if error is from Cloudflare connection timeout
+ */
+export function isCloudflareError(error: any): boolean {
+  return error?.code === 522 || error?.code === "522";
+}
+
+/**
+ * Checks if error is authentication/authorization related
+ * @param error - Error object to check
+ * @returns True if error is auth-related (401, 403)
+ */
+export function isAuthError(error: any): boolean {
+  const code = error?.code;
+  return code === 401 || code === 403 || code === "401" || code === "403";
+}
+
+/**
+ * Error categorization helpers for smart fallback logic
+ */
+
+/**
+ * Checks if an error is retryable (network issues, rate limits, etc.)
+ * @param errorMessage - Error message to check
+ * @returns True if error is retryable
+ */
+export function isRetryableError(errorMessage: string): boolean {
+  const retryableErrors = [
+    "rate limit",
+    "timeout",
+    "network",
+    "temporary",
+    "503",
+    "502",
+    "429"
+  ];
+  return retryableErrors.some(error =>
+    errorMessage.toLowerCase().includes(error)
+  );
+}
+
+/**
+ * Checks if an error indicates bulk operations are not supported
+ * @param errorMessage - Error message to check
+ * @returns True if bulk operations not supported
+ */
+export function isBulkNotSupportedError(errorMessage: string): boolean {
+  const notSupportedErrors = [
+    "method not found",
+    "not implemented",
+    "unsupported",
+    "not available",
+    "404"
+  ];
+  return notSupportedErrors.some(error =>
+    errorMessage.toLowerCase().includes(error)
+  );
+}
+
+/**
+ * Checks if an error is critical (authentication, authorization, permissions)
+ * @param errorMessage - Error message to check
+ * @returns True if error is critical
+ */
+export function isCriticalError(errorMessage: string): boolean {
+  const criticalErrors = [
+    "authentication",
+    "authorization",
+    "permission",
+    "forbidden",
+    "401",
+    "403"
+  ];
+  return criticalErrors.some(error =>
+    errorMessage.toLowerCase().includes(error)
+  );
+}

package/src/shared/functionManager.ts

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import chalk from "chalk";
 import pLimit from "p-limit";
 import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { MessageFormatter } from "./messageFormatter.js";
 
 /**
  * Validates and filters events array for Appwrite functions
@@ -64,7 +65,7 @@ export class FunctionManager {
     } = options;
 
     if (verbose) {
-      console.log(chalk.blue(`🔍 Searching for function: ${functionName}`));
+      MessageFormatter.info(`Searching for function: ${functionName}`, { prefix: "Functions" });
     }
 
     // Normalize function name for comparison
@@ -76,7 +77,7 @@ export class FunctionManager {
     for (const path of standardPaths) {
       if (await this.isValidFunctionDirectory(path)) {
         if (verbose) {
-          console.log(chalk.green(`✓ Found function at standard location: ${path}`));
+          MessageFormatter.success(`Found function at standard location: ${path}`, { prefix: "Functions" });
         }
         return path;
       }
@@ -92,7 +93,7 @@ export class FunctionManager {
         );
         if (foundPath) {
           if (verbose) {
-            console.log(chalk.green(`✓ Found function via fuzzy search: ${foundPath}`));
+            MessageFormatter.success(`Found function via fuzzy search: ${foundPath}`, { prefix: "Functions" });
           }
           return foundPath;
         }
@@ -100,7 +101,7 @@ export class FunctionManager {
     }
 
     if (verbose) {
-      console.log(chalk.yellow(`⚠ Function directory not found: ${functionName}`));
+      MessageFormatter.warning(`Function directory not found: ${functionName}`, { prefix: "Functions" });
     }
     return null;
   }
@@ -175,7 +176,7 @@ export class FunctionManager {
       }
     } catch (error) {
       if (verbose) {
-        console.log(chalk.gray(`Skipping inaccessible directory: ${searchPath}`));
+        MessageFormatter.debug(`Skipping inaccessible directory: ${searchPath}`, undefined, { prefix: "Functions" });
       }
     }
 
@@ -248,9 +249,9 @@ export class FunctionManager {
 
     return await functionLimit(async () => {
       if (verbose) {
-        console.log(chalk.blue(`🚀 Deploying function: ${functionConfig.name}`));
-        console.log(chalk.gray(`   Path: ${functionPath}`));
-        console.log(chalk.gray(`   Entrypoint: ${entrypoint}`));
+        MessageFormatter.processing(`Deploying function: ${functionConfig.name}`, { prefix: "Functions" });
+        MessageFormatter.debug(`Path: ${functionPath}`, undefined, { prefix: "Functions" });
+        MessageFormatter.debug(`Entrypoint: ${entrypoint}`, undefined, { prefix: "Functions" });
       }
 
       // Validate function directory
@@ -265,7 +266,7 @@ export class FunctionManager {
         functionExists = true;
       } catch (error) {
         if (verbose) {
-          console.log(chalk.yellow(`Function ${functionConfig.$id} does not exist, creating...`));
+          MessageFormatter.info(`Function ${functionConfig.$id} does not exist, creating...`, { prefix: "Functions" });
         }
       }
 
@@ -289,7 +290,7 @@ export class FunctionManager {
       );
 
       if (verbose) {
-        console.log(chalk.green(`✅ Function ${functionConfig.name} deployed successfully`));
+        MessageFormatter.success(`Function ${functionConfig.name} deployed successfully`, { prefix: "Functions" });
       }
 
       return deployment;
@@ -303,7 +304,7 @@ export class FunctionManager {
     const { verbose = false } = options;
 
     if (verbose) {
-      console.log(chalk.blue(`Creating function: ${functionConfig.name}`));
+      MessageFormatter.processing(`Creating function: ${functionConfig.name}`, { prefix: "Functions" });
     }
 
     return await tryAwaitWithRetry(async () => {
@@ -336,7 +337,7 @@ export class FunctionManager {
     const { verbose = false } = options;
 
     if (verbose) {
-      console.log(chalk.blue(`Updating function: ${functionConfig.name}`));
+      MessageFormatter.processing(`Updating function: ${functionConfig.name}`, { prefix: "Functions" });
     }
 
     return await tryAwaitWithRetry(async () => {
@@ -373,14 +374,14 @@ export class FunctionManager {
     const { platform } = await import("node:os");
 
     if (verbose) {
-      console.log(chalk.blue("Executing pre-deploy commands..."));
+      MessageFormatter.processing("Executing pre-deploy commands...", { prefix: "Functions" });
     }
 
     const isWindows = platform() === "win32";
 
     for (const command of commands) {
       if (verbose) {
-        console.log(chalk.gray(`  $ ${command}`));
+        MessageFormatter.debug(`$ ${command}`, undefined, { prefix: "Functions" });
       }
 
       try {
@@ -391,13 +392,13 @@ export class FunctionManager {
           windowsHide: true,
         });
       } catch (error) {
-        console.error(chalk.red(`Failed to execute command: ${command}`));
+        MessageFormatter.error(`Failed to execute command: ${command}`, error as Error, { prefix: "Functions" });
         throw error;
       }
     }
 
     if (verbose) {
-      console.log(chalk.green("✓ Pre-deploy commands completed"));
+      MessageFormatter.success("Pre-deploy commands completed", { prefix: "Functions" });
     }
   }
 
@@ -415,7 +416,7 @@ export class FunctionManager {
 
     try {
       if (verbose) {
-        console.log(chalk.blue("Creating deployment archive..."));
+        MessageFormatter.processing("Creating deployment archive...", { prefix: "Functions" });
       }
 
       // Create tarball
@@ -431,9 +432,9 @@ export class FunctionManager {
               relativePath.includes(`/${pattern.toLowerCase()}`) ||
               relativePath.includes(`\\${pattern.toLowerCase()}`)
             );
-            
+
             if (shouldIgnore && verbose) {
-              console.log(chalk.gray(`  Ignoring: ${path}`));
+              MessageFormatter.debug(`Ignoring: ${path}`, undefined, { prefix: "Functions" });
             }
             
             return !shouldIgnore;
@@ -450,7 +451,7 @@ export class FunctionManager {
       );
 
       if (verbose) {
-        console.log(chalk.blue("Uploading deployment..."));
+        MessageFormatter.processing("Uploading deployment...", { prefix: "Functions" });
       }
 
       const deployment = await tryAwaitWithRetry(async () => {