appwrite-utils-cli 0.10.86 → 1.0.1

package/src/shared/logging.ts

@@ -0,0 +1,74 @@
+import winston from "winston";
+import fs from "fs";
+import path from "path";
+
+export interface LoggingConfig {
+  enabled: boolean;
+  level: string;
+  logDirectory?: string;
+  console: boolean;
+}
+
+const DEFAULT_LOGGING_CONFIG: LoggingConfig = {
+  enabled: false,
+  level: "info",
+  console: false,
+};
+
+let loggingConfig: LoggingConfig = DEFAULT_LOGGING_CONFIG;
+
+export const configureLogging = (config: Partial<LoggingConfig> = {}) => {
+  loggingConfig = { ...DEFAULT_LOGGING_CONFIG, ...config };
+};
+
+const createLogger = () => {
+  const transports: winston.transport[] = [];
+
+  // Add console transport if enabled
+  if (loggingConfig.console) {
+    transports.push(new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      )
+    }));
+  }
+
+  // Add file transports if logging is enabled
+  if (loggingConfig.enabled) {
+    const logDir = loggingConfig.logDirectory || path.join(process.cwd(), "zlogs");
+    
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    transports.push(
+      new winston.transports.File({
+        filename: path.join(logDir, "error.log"),
+        level: "error",
+      }),
+      new winston.transports.File({
+        filename: path.join(logDir, "combined.log"),
+      })
+    );
+  }
+
+  return winston.createLogger({
+    level: loggingConfig.level,
+    format: winston.format.combine(
+      winston.format.timestamp(),
+      winston.format.errors({ stack: true }),
+      winston.format.json()
+    ),
+    defaultMeta: { service: "appwrite-utils-cli" },
+    transports,
+    silent: !loggingConfig.enabled && !loggingConfig.console,
+  });
+};
+
+export let logger = createLogger();
+
+// Recreate logger when config changes
+export const updateLogger = () => {
+  logger = createLogger();
+};

package/src/shared/messageFormatter.ts

@@ -0,0 +1,195 @@
+import chalk from "chalk";
+import { logger } from "./logging.js";
+
+export interface MessageOptions {
+  prefix?: string;
+  skipLogging?: boolean;
+  logLevel?: "info" | "warn" | "error" | "debug";
+}
+
+export class MessageFormatter {
+  static success(message: string, options: MessageOptions = {}) {
+    const formatted = `${chalk.green("✅")} ${options.prefix ? `${options.prefix}: ` : ""}${message}`;
+    console.log(formatted);
+    
+    if (!options.skipLogging) {
+      logger.info(`SUCCESS: ${options.prefix ? `${options.prefix}: ` : ""}${message}`);
+    }
+  }
+
+  static error(message: string, error?: Error | string, options: MessageOptions = {}) {
+    const errorDetails = error instanceof Error ? error.message : error;
+    const formatted = `${chalk.red("❌")} ${options.prefix ? `${options.prefix}: ` : ""}${message}${errorDetails ? `\n   ${chalk.gray(errorDetails)}` : ""}`;
+    console.error(formatted);
+    
+    if (!options.skipLogging) {
+      logger.error(`ERROR: ${options.prefix ? `${options.prefix}: ` : ""}${message}`, {
+        error: errorDetails,
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    }
+  }
+
+  static warning(message: string, options: MessageOptions = {}) {
+    const formatted = `${chalk.yellow("⚠️")} ${options.prefix ? `${options.prefix}: ` : ""}${message}`;
+    console.log(formatted);
+    
+    if (!options.skipLogging) {
+      logger.warn(`WARNING: ${options.prefix ? `${options.prefix}: ` : ""}${message}`);
+    }
+  }
+
+  static info(message: string, options: MessageOptions = {}) {
+    const formatted = `${chalk.blue("ℹ️")} ${options.prefix ? `${options.prefix}: ` : ""}${message}`;
+    console.log(formatted);
+    
+    if (!options.skipLogging) {
+      logger.info(`INFO: ${options.prefix ? `${options.prefix}: ` : ""}${message}`);
+    }
+  }
+
+  static step(step: number, total: number, message: string, options: MessageOptions = {}) {
+    const formatted = `${chalk.cyan(`[${step}/${total}]`)} ${options.prefix ? `${options.prefix}: ` : ""}${message}`;
+    console.log(formatted);
+    
+    if (!options.skipLogging) {
+      logger.info(`STEP ${step}/${total}: ${options.prefix ? `${options.prefix}: ` : ""}${message}`);
+    }
+  }
+
+  static progress(message: string, options: MessageOptions = {}) {
+    const formatted = `${chalk.gray("⏳")} ${options.prefix ? `${options.prefix}: ` : ""}${message}`;
+    console.log(formatted);
+    
+    if (!options.skipLogging) {
+      logger.debug(`PROGRESS: ${options.prefix ? `${options.prefix}: ` : ""}${message}`);
+    }
+  }
+
+  static debug(message: string, data?: any, options: MessageOptions = {}) {
+    if (process.env.NODE_ENV === "development" || process.env.DEBUG) {
+      const formatted = `${chalk.magenta("🔍")} ${options.prefix ? `${options.prefix}: ` : ""}${message}`;
+      console.log(formatted);
+      if (data) {
+        console.log(chalk.gray(JSON.stringify(data, null, 2)));
+      }
+    }
+    
+    if (!options.skipLogging) {
+      logger.debug(`DEBUG: ${options.prefix ? `${options.prefix}: ` : ""}${message}`, data);
+    }
+  }
+
+  static banner(title: string, subtitle?: string) {
+    const divider = chalk.cyan("═".repeat(60));
+    console.log(`\n${divider}`);
+    console.log(chalk.cyan.bold(`  ${title}`));
+    if (subtitle) {
+      console.log(chalk.gray(`  ${subtitle}`));
+    }
+    console.log(`${divider}\n`);
+  }
+
+  static section(title: string) {
+    console.log(`\n${chalk.bold.underline(title)}`);
+  }
+
+  static list(items: string[], title?: string) {
+    if (title) {
+      console.log(chalk.bold(title));
+    }
+    items.forEach((item, index) => {
+      console.log(`${chalk.gray(`  ${index + 1}.`)} ${item}`);
+    });
+  }
+
+  static table(data: Record<string, string | number>[], headers?: string[]) {
+    if (data.length === 0) return;
+    
+    const keys = headers || Object.keys(data[0]);
+    const maxWidths = keys.map(key => 
+      Math.max(
+        key.length,
+        ...data.map(row => String(row[key]).length)
+      )
+    );
+
+    // Header
+    const headerRow = keys.map((key, i) => 
+      chalk.bold(key.padEnd(maxWidths[i]))
+    ).join(" │ ");
+    console.log(`┌─${keys.map((_, i) => "─".repeat(maxWidths[i])).join("─┼─")}─┐`);
+    console.log(`│ ${headerRow} │`);
+    console.log(`├─${keys.map((_, i) => "─".repeat(maxWidths[i])).join("─┼─")}─┤`);
+
+    // Rows
+    data.forEach(row => {
+      const dataRow = keys.map((key, i) => 
+        String(row[key]).padEnd(maxWidths[i])
+      ).join(" │ ");
+      console.log(`│ ${dataRow} │`);
+    });
+    console.log(`└─${keys.map((_, i) => "─".repeat(maxWidths[i])).join("─┴─")}─┘`);
+  }
+
+  static operationSummary(title: string, stats: Record<string, string | number>, duration?: number) {
+    this.section(`${title} Summary`);
+    
+    Object.entries(stats).forEach(([key, value]) => {
+      const formattedKey = key.replace(/([A-Z])/g, ' $1').replace(/^./, str => str.toUpperCase());
+      console.log(`${chalk.gray("●")} ${formattedKey}: ${chalk.cyan(String(value))}`);
+    });
+    
+    if (duration) {
+      console.log(`${chalk.gray("●")} Duration: ${chalk.cyan(this.formatDuration(duration))}`);
+    }
+    console.log();
+  }
+
+  static formatBytes(bytes: number): string {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unitIndex = 0;
+    
+    while (size >= 1024 && unitIndex < units.length - 1) {
+      size /= 1024;
+      unitIndex++;
+    }
+    
+    return `${size.toFixed(1)} ${units[unitIndex]}`;
+  }
+
+  static formatDuration(ms: number): string {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+    } else if (minutes > 0) {
+      return `${minutes}m ${seconds % 60}s`;
+    } else {
+      return `${seconds}s`;
+    }
+  }
+
+  static formatNumber(num: number): string {
+    return num.toLocaleString();
+  }
+}
+
+export const Messages = {
+  CONFIG_NOT_FOUND: "Appwrite configuration not found. Run 'appwrite-migrate setup' first.",
+  CONFIG_LOADED: (type: string, path: string) => `Loaded ${type} configuration from ${path}`,
+  DATABASE_CONNECTION_FAILED: "Failed to connect to Appwrite. Check your endpoint and API key.",
+  OPERATION_CANCELLED: "Operation cancelled by user.",
+  OPERATION_COMPLETED: (operation: string) => `${operation} completed successfully`,
+  BACKUP_STARTED: (database: string) => `Starting backup for database: ${database}`,
+  BACKUP_COMPLETED: (database: string, size: number) => `Backup completed for ${database} (${MessageFormatter.formatBytes(size)})`,
+  IMPORT_STARTED: (collections: number) => `Starting import process for ${collections} collection(s)`,
+  IMPORT_COMPLETED: (documents: number) => `Import completed. Processed ${MessageFormatter.formatNumber(documents)} documents`,
+  FUNCTION_DEPLOYED: (name: string) => `Function '${name}' deployed successfully`,
+  FUNCTION_DEPLOYMENT_FAILED: (name: string, error: string) => `Function '${name}' deployment failed: ${error}`,
+  TRANSFER_STARTED: (source: string, target: string) => `Starting transfer from ${source} to ${target}`,
+  TRANSFER_COMPLETED: (items: number) => `Transfer completed. Moved ${MessageFormatter.formatNumber(items)} items`,
+} as const;

package/src/{migrations/migrationHelper.ts → shared/migrationHelpers.ts}

@@ -1,5 +1,5 @@
 import { ID, Query, type Databases } from "node-appwrite";
-import { BatchSchema, OperationSchema, type Operation } from "./backup.js";
+import { BatchSchema, OperationSchema, type Operation } from "../storage/schemas.js";
 import { AttributeMappingsSchema } from "appwrite-utils";
 import { z } from "zod";
 import { logger } from "./logging.js";
@@ -29,8 +29,14 @@ export type ContextObject = z.infer<typeof ContextObject>;
 export const createOrFindAfterImportOperation = async (
   database: Databases,
   collectionId: string,
-  context: ContextObject
+  context: ContextObject,
+  useMigrations: boolean = true
 ) => {
+  if (!useMigrations) {
+    logger.info("Migrations disabled, skipping after import operation tracking");
+    return;
+  }
+
   let operation = await findOrCreateOperation(
     database,
     collectionId,
@@ -69,8 +75,14 @@ export const addBatch = async (database: Databases, data: string) => {
 
 export const getAfterImportOperations = async (
   database: Databases,
-  collectionId: string
+  collectionId: string,
+  useMigrations: boolean = true
 ) => {
+  if (!useMigrations) {
+    logger.info("Migrations disabled, returning empty operations list");
+    return [];
+  }
+
   let lastDocumentId: string | undefined;
   const allOperations = [];
   let total = 0;
@@ -149,8 +161,14 @@ export const findOrCreateOperation = async (
 export const updateOperation = async (
   database: Databases,
   operationId: string,
-  updateFields: any
+  updateFields: any,
+  useMigrations: boolean = true
 ) => {
+  if (!useMigrations) {
+    logger.info("Migrations disabled, skipping operation update");
+    return;
+  }
+
   await tryAwaitWithRetry(
     async () =>
       await database.updateDocument(

package/src/{migrations/helper.ts → shared/operationLogger.ts}

@@ -7,8 +7,13 @@ export const logOperation = async (
   db: Databases,
   dbId: string,
   operationDetails: OperationCreate,
-  operationId?: string
-): Promise<Models.Document> => {
+  operationId?: string,
+  useMigrations: boolean = true
+): Promise<Models.Document | null> => {
+  if (!useMigrations) {
+    console.log("Migrations disabled, skipping operation logging");
+    return null;
+  }
   try {
     let operation;
     if (operationId) {

package/src/{migrations/queue.ts → shared/operationQueue.ts}

@@ -1,6 +1,6 @@
 import { Query, type Databases, type Models } from "node-appwrite";
 import type { Attribute } from "appwrite-utils";
-import { createOrUpdateAttribute } from "./attributes.js";
+import { createOrUpdateAttribute } from "../collections/attributes.js";
 import { fetchAndCacheCollectionByName } from "../collections/methods.js";
 import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
 

package/src/shared/progressManager.ts

@@ -0,0 +1,278 @@
+import cliProgress from "cli-progress";
+import chalk from "chalk";
+import { MessageFormatter } from "./messageFormatter.js";
+
+export interface ProgressOptions {
+  title?: string;
+  showETA?: boolean;
+  showSpeed?: boolean;
+  showPercentage?: boolean;
+  width?: number;
+  format?: string;
+}
+
+export class ProgressManager {
+  private static instances = new Map<string, ProgressManager>();
+  private bar: cliProgress.SingleBar;
+  private startTime: number;
+  private totalItems: number;
+  private completed: number = 0;
+  private id: string;
+  private title: string;
+
+  private constructor(id: string, total: number, options: ProgressOptions = {}) {
+    this.id = id;
+    this.totalItems = total;
+    this.startTime = Date.now();
+    this.title = options.title || "Processing";
+
+    const format = options.format || 
+      `${chalk.cyan(this.title)} ${chalk.yellow("[{bar}]")} {percentage}% | {value}/{total} | ETA: {eta}s | Speed: {speed}/s`;
+
+    this.bar = new cliProgress.SingleBar({
+      format,
+      barCompleteChar: '█',
+      barIncompleteChar: '░',
+      hideCursor: true,
+      clearOnComplete: false,
+      stopOnComplete: true,
+      ...options,
+    }, cliProgress.Presets.shades_classic);
+
+    this.bar.start(total, 0);
+  }
+
+  static create(id: string, total: number, options: ProgressOptions = {}): ProgressManager {
+    if (ProgressManager.instances.has(id)) {
+      const existing = ProgressManager.instances.get(id)!;
+      existing.stop();
+    }
+
+    const instance = new ProgressManager(id, total, options);
+    ProgressManager.instances.set(id, instance);
+    return instance;
+  }
+
+  static get(id: string): ProgressManager | undefined {
+    return ProgressManager.instances.get(id);
+  }
+
+  update(current: number, detail?: string) {
+    this.completed = current;
+    
+    // Calculate speed
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    const speed = elapsed > 0 ? Math.round(current / elapsed) : 0;
+
+    this.bar.update(current, {
+      speed,
+      detail: detail || '',
+    });
+
+    if (detail) {
+      // Update the payload for custom formatting
+      this.bar.update(current, { detail });
+    }
+  }
+
+  increment(amount: number = 1, detail?: string) {
+    this.update(this.completed + amount, detail);
+  }
+
+  setTotal(total: number) {
+    this.totalItems = total;
+    this.bar.setTotal(total);
+  }
+
+  stop(showSummary: boolean = true) {
+    this.bar.stop();
+    
+    if (showSummary) {
+      const duration = Date.now() - this.startTime;
+      const rate = this.completed / (duration / 1000);
+      
+      MessageFormatter.success(
+        `${this.title} completed`,
+        { 
+          prefix: `${this.completed}/${this.totalItems} items in ${MessageFormatter.formatDuration(duration)} (${rate.toFixed(1)}/s)` 
+        }
+      );
+    }
+
+    ProgressManager.instances.delete(this.id);
+  }
+
+  fail(error: string) {
+    this.bar.stop();
+    MessageFormatter.error(`${this.title} failed: ${error}`);
+    ProgressManager.instances.delete(this.id);
+  }
+
+  getStats() {
+    const duration = Date.now() - this.startTime;
+    const rate = this.completed / (duration / 1000);
+    
+    return {
+      completed: this.completed,
+      total: this.totalItems,
+      percentage: (this.completed / this.totalItems) * 100,
+      duration,
+      rate,
+      remaining: this.totalItems - this.completed,
+      eta: this.completed > 0 ? ((this.totalItems - this.completed) / rate) * 1000 : 0,
+    };
+  }
+
+  static stopAll() {
+    for (const [id, instance] of ProgressManager.instances) {
+      instance.stop(false);
+    }
+    ProgressManager.instances.clear();
+  }
+}
+
+export class MultiProgressManager {
+  private multiBar: cliProgress.MultiBar;
+  private bars = new Map<string, cliProgress.SingleBar>();
+  private startTime: number;
+
+  constructor(options: ProgressOptions = {}) {
+    this.startTime = Date.now();
+    
+    this.multiBar = new cliProgress.MultiBar({
+      clearOnComplete: false,
+      hideCursor: true,
+      format: options.format || `${chalk.cyan("{title}")} ${chalk.yellow("[{bar}]")} {percentage}% | {value}/{total} | {detail}`,
+      barCompleteChar: '█',
+      barIncompleteChar: '░',
+    }, cliProgress.Presets.shades_classic);
+  }
+
+  addTask(id: string, total: number, title: string): void {
+    const bar = this.multiBar.create(total, 0, {
+      title: title.padEnd(20),
+      detail: '',
+    });
+    this.bars.set(id, bar);
+  }
+
+  updateTask(id: string, current: number, detail?: string): void {
+    const bar = this.bars.get(id);
+    if (bar) {
+      bar.update(current, {
+        detail: detail || '',
+      });
+    }
+  }
+
+  incrementTask(id: string, amount: number = 1, detail?: string): void {
+    const bar = this.bars.get(id);
+    if (bar) {
+      const currentValue = bar.getProgress() * bar.getTotal();
+      this.updateTask(id, currentValue + amount, detail);
+    }
+  }
+
+  completeTask(id: string): void {
+    const bar = this.bars.get(id);
+    if (bar) {
+      bar.update(bar.getTotal());
+    }
+  }
+
+  failTask(id: string, error: string): void {
+    const bar = this.bars.get(id);
+    if (bar) {
+      bar.update(bar.getProgress() * bar.getTotal(), {
+        detail: chalk.red(`Failed: ${error}`),
+      });
+    }
+  }
+
+  stop(showSummary: boolean = true): void {
+    this.multiBar.stop();
+    
+    if (showSummary) {
+      const duration = Date.now() - this.startTime;
+      MessageFormatter.success(
+        `All tasks completed in ${MessageFormatter.formatDuration(duration)}`
+      );
+    }
+  }
+
+  getTaskStats(id: string) {
+    const bar = this.bars.get(id);
+    if (!bar) return null;
+
+    const progress = bar.getProgress();
+    const total = bar.getTotal();
+    const completed = Math.floor(progress * total);
+
+    return {
+      completed,
+      total,
+      percentage: progress * 100,
+      remaining: total - completed,
+    };
+  }
+
+  getAllStats() {
+    const stats = new Map<string, any>();
+    for (const [id, bar] of this.bars) {
+      stats.set(id, this.getTaskStats(id));
+    }
+    return stats;
+  }
+}
+
+// Utility functions for common progress scenarios
+export const ProgressUtils = {
+  async withProgress<T>(
+    id: string,
+    total: number,
+    title: string,
+    operation: (progress: ProgressManager) => Promise<T>
+  ): Promise<T> {
+    const progress = ProgressManager.create(id, total, { title });
+    try {
+      const result = await operation(progress);
+      progress.stop();
+      return result;
+    } catch (error) {
+      progress.fail(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  },
+
+  async processArrayWithProgress<T, R>(
+    items: T[],
+    processor: (item: T, index: number) => Promise<R>,
+    options: { title?: string; batchSize?: number; showDetail?: boolean } = {}
+  ): Promise<R[]> {
+    const { title = "Processing items", batchSize = 1, showDetail = true } = options;
+    const progress = ProgressManager.create(`process-${Date.now()}`, items.length, { title });
+    
+    const results: R[] = [];
+    
+    try {
+      for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const batchResults = await Promise.all(
+          batch.map(async (item, batchIndex) => {
+            const result = await processor(item, i + batchIndex);
+            const detail = showDetail ? `Item ${i + batchIndex + 1}: ${String(item).slice(0, 30)}...` : undefined;
+            progress.update(i + batchIndex + 1, detail);
+            return result;
+          })
+        );
+        results.push(...batchResults);
+      }
+      
+      progress.stop();
+      return results;
+    } catch (error) {
+      progress.fail(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  },
+};