appwrite-utils-cli 1.5.2 → 1.6.0

package/dist/schemas/authUser.d.ts

@@ -11,8 +11,8 @@ export declare const AuthUserSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type AuthUser = z.infer<typeof AuthUserSchema>;
 export declare const AuthUserCreateSchema: z.ZodObject<{
-    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     $createdAt: z.ZodOptional<z.ZodString>;
     $updatedAt: z.ZodOptional<z.ZodString>;
     phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/setupController.js

@@ -2,6 +2,7 @@ import { setupDirsFiles } from "./utils/setupFiles.js";
 import { loadConfig } from "./utils/loadConfigs.js";
 import path from "path";
 import fs from "fs";
+import { MessageFormatter } from "./shared/messageFormatter.js";
 export class SetupController {
     currentDir;
     config = null;
@@ -10,7 +11,7 @@ export class SetupController {
     }
     async runSetup(withExampleData = false) {
         await setupDirsFiles(withExampleData, this.currentDir);
-        console.log("Setup completed successfully.");
+        MessageFormatter.success("Setup completed successfully", { prefix: "Setup" });
     }
     async loadConfig() {
         if (this.hasExistingConfig()) {
@@ -20,7 +21,7 @@ export class SetupController {
                 return this.config;
             }
             catch (error) {
-                console.error("Error loading config:", error);
+                MessageFormatter.error("Error loading config", error, { prefix: "Setup" });
                 return null;
             }
         }

package/dist/shared/backupMetadataSchema.d.ts

@@ -0,0 +1,94 @@
+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 declare const BACKUP_TYPES: readonly ["database", "bucket", "comprehensive"];
+export declare const BACKUP_FORMATS: readonly ["json", "zip"];
+export declare const BACKUP_STATUSES: readonly ["completed", "partial", "failed"];
+export declare const RESTORATION_STATUSES: readonly ["completed", "partial", "failed", "not_restored"];
+export declare const BackupTypeSchema: z.ZodEnum<{
+    bucket: "bucket";
+    database: "database";
+    comprehensive: "comprehensive";
+}>;
+export declare const BackupFormatSchema: z.ZodEnum<{
+    json: "json";
+    zip: "zip";
+}>;
+export declare const BackupStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    partial: "partial";
+}>;
+export declare const RestorationStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    partial: "partial";
+    not_restored: "not_restored";
+}>;
+export interface BackupMetadata {
+    $id: string;
+    $createdAt: string;
+    $updatedAt: string;
+    backupType: BackupType;
+    backupId: string;
+    manifestFileId?: string;
+    format: BackupFormat;
+    sizeBytes: number;
+    databaseId?: string;
+    bucketId?: string;
+    comprehensiveBackupId?: string;
+    collections?: number;
+    documents?: number;
+    fileCount?: number;
+    status: BackupStatus;
+    error?: string;
+    restoredAt?: string;
+    restorationStatus: RestorationStatus;
+    restorationError?: string;
+}
+export declare const BackupMetadataSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $createdAt: z.ZodString;
+    $updatedAt: z.ZodString;
+    backupType: z.ZodEnum<{
+        bucket: "bucket";
+        database: "database";
+        comprehensive: "comprehensive";
+    }>;
+    backupId: z.ZodString;
+    manifestFileId: z.ZodOptional<z.ZodString>;
+    format: z.ZodEnum<{
+        json: "json";
+        zip: "zip";
+    }>;
+    sizeBytes: z.ZodNumber;
+    databaseId: z.ZodOptional<z.ZodString>;
+    bucketId: z.ZodOptional<z.ZodString>;
+    comprehensiveBackupId: z.ZodOptional<z.ZodString>;
+    collections: z.ZodOptional<z.ZodNumber>;
+    documents: z.ZodOptional<z.ZodNumber>;
+    fileCount: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        partial: "partial";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+    restoredAt: z.ZodOptional<z.ZodString>;
+    restorationStatus: z.ZodDefault<z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        partial: "partial";
+        not_restored: "not_restored";
+    }>>;
+    restorationError: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const BACKUP_TABLE_ID = "appwrite_backups";
+export declare const BACKUP_TABLE_NAME = "Backup Tracking";

package/dist/shared/backupMetadataSchema.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export const BACKUP_TYPES = ['database', 'bucket', 'comprehensive'];
+export const BACKUP_FORMATS = ['json', 'zip'];
+export const BACKUP_STATUSES = ['completed', 'partial', 'failed'];
+export const RESTORATION_STATUSES = ['completed', 'partial', 'failed', 'not_restored'];
+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 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/dist/shared/backupTracking.d.ts

@@ -0,0 +1,18 @@
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { type BackupMetadata } from "./backupMetadataSchema.js";
+/**
+ * Creates the backup tracking table in the specified database
+ */
+export declare function createBackupTrackingTable(db: DatabaseAdapter, databaseId: string): Promise<void>;
+/**
+ * Records backup metadata in the tracking table
+ */
+export declare function recordBackup(db: DatabaseAdapter, databaseId: string, metadata: Omit<BackupMetadata, '$id' | '$createdAt' | '$updatedAt'>): Promise<BackupMetadata>;
+/**
+ * Lists all backups for a database, sorted by creation date (newest first)
+ */
+export declare function listBackups(db: DatabaseAdapter, databaseId: string): Promise<BackupMetadata[]>;
+/**
+ * Gets the most recent backup for a database
+ */
+export declare function getLastBackup(db: DatabaseAdapter, databaseId: string): Promise<BackupMetadata | null>;

package/dist/shared/backupTracking.js

@@ -0,0 +1,176 @@
+import { logger } from "./logging.js";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import { BACKUP_TABLE_ID, BACKUP_TABLE_NAME, BackupMetadataSchema } from "./backupMetadataSchema.js";
+/**
+ * Checks if backup tracking table exists in database
+ */
+async function tableExists(db, databaseId) {
+    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, databaseId) {
+    // 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",
+            size: 50,
+            required: true
+        },
+        {
+            key: "databaseId",
+            type: "string",
+            size: 50,
+            required: true
+        },
+        {
+            key: "sizeBytes",
+            type: "integer",
+            required: true
+        },
+        {
+            key: "collections",
+            type: "integer",
+            required: true
+        },
+        {
+            key: "documents",
+            type: "integer",
+            required: true
+        },
+        {
+            key: "format",
+            type: "enum",
+            elements: ["json", "zip"],
+            required: true
+        },
+        {
+            key: "status",
+            type: "enum",
+            elements: ["completed", "failed"],
+            required: true
+        },
+        {
+            key: "error",
+            type: "string",
+            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, databaseId, metadata) {
+    // 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;
+}
+/**
+ * Lists all backups for a database, sorted by creation date (newest first)
+ */
+export async function listBackups(db, databaseId) {
+    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 || []);
+    }
+    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, databaseId) {
+    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];
+        }
+        return null;
+    }
+    catch (error) {
+        logger.debug("No backup found or table doesn't exist", { databaseId });
+        return null;
+    }
+}

package/dist/shared/confirmationDialogs.js

@@ -9,16 +9,16 @@ export class ConfirmationDialogs {
         if (options.skipConfirmation) {
             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([{
                     type: 'input',
@@ -47,9 +47,9 @@ export class ConfirmationDialogs {
     static async promptForBackup(options) {
         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([{
                 type: 'list',
@@ -68,11 +68,11 @@ export class ConfirmationDialogs {
      * Shows a final confirmation before proceeding with an operation
      */
     static async finalConfirmation(operation, details) {
-        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 });
             });
         }
         const { proceed } = await inquirer.prompt([{
@@ -152,17 +152,17 @@ 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) {
             const { confirmed } = await inquirer.prompt([{

package/dist/shared/errorUtils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare function getErrorMessage(error: unknown): string;
+/**
+ * Normalizes unknown error to Error instance
+ * @param error - Error of unknown type
+ * @returns Normalized Error object
+ */
+export declare function normalizeError(error: unknown): 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 declare function isConflictError(error: any): boolean;
+/**
+ * Checks if error is a Cloudflare error (522)
+ * @param error - Error object to check
+ * @returns True if error is from Cloudflare connection timeout
+ */
+export declare function isCloudflareError(error: any): boolean;
+/**
+ * Checks if error is authentication/authorization related
+ * @param error - Error object to check
+ * @returns True if error is auth-related (401, 403)
+ */
+export declare function isAuthError(error: any): boolean;
+/**
+ * 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 declare function isRetryableError(errorMessage: string): boolean;
+/**
+ * Checks if an error indicates bulk operations are not supported
+ * @param errorMessage - Error message to check
+ * @returns True if bulk operations not supported
+ */
+export declare function isBulkNotSupportedError(errorMessage: string): boolean;
+/**
+ * Checks if an error is critical (authentication, authorization, permissions)
+ * @param errorMessage - Error message to check
+ * @returns True if error is critical
+ */
+export declare function isCriticalError(errorMessage: string): boolean;

package/dist/shared/errorUtils.js

@@ -0,0 +1,95 @@
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    const criticalErrors = [
+        "authentication",
+        "authorization",
+        "permission",
+        "forbidden",
+        "401",
+        "403"
+    ];
+    return criticalErrors.some(error => errorMessage.toLowerCase().includes(error));
+}