appwrite-utils-cli 1.5.1 → 1.6.0

package/dist/backups/tracking/centralizedTracking.js

@@ -0,0 +1,274 @@
+import { logger } from "../../shared/logging.js";
+import { tryAwaitWithRetry } from "../../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import { BACKUP_TABLE_ID, BACKUP_TABLE_NAME, BackupMetadataSchema } from "../../shared/backupMetadataSchema.js";
+/**
+ * Centralized backup tracking system
+ *
+ * All backups (databases, buckets, comprehensive) are tracked in a single
+ * database selected by the user, providing a centralized backup registry.
+ */
+/**
+ * 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 centralized backup tracking table with enhanced schema
+ */
+export async function createCentralizedBackupTrackingTable(db, databaseId) {
+    // Check if table already exists
+    const exists = await tableExists(db, databaseId);
+    if (exists) {
+        // Table exists - validate its schema
+        try {
+            const tableData = await db.getTable({ databaseId, tableId: BACKUP_TABLE_ID });
+            const existingAttrs = (tableData.data.attributes || []);
+            // Expected attribute keys from our schema
+            const expectedAttrKeys = [
+                "backupType", "backupId", "manifestFileId", "format", "sizeBytes",
+                "databaseId", "bucketId", "comprehensiveBackupId",
+                "collections", "documents", "fileCount",
+                "status", "error",
+                "restoredAt", "restorationStatus", "restorationError"
+            ];
+            // Existing attribute keys
+            const existingAttrKeys = new Set(existingAttrs.map((a) => a.key));
+            // Check if they match
+            const hasAllAttributes = expectedAttrKeys.every(key => existingAttrKeys.has(key));
+            // Check if any have wrong sizes (old 10000 vs new 1000)
+            const hasWrongSizes = existingAttrs.some((a) => (a.key === 'error' || a.key === 'restorationError') && a.size === 10000);
+            if (!hasAllAttributes || hasWrongSizes) {
+                logger.warn("Backup table exists but has incorrect schema - recreating", {
+                    tableId: BACKUP_TABLE_ID,
+                    hasAllAttributes,
+                    hasWrongSizes,
+                    existingCount: existingAttrKeys.size,
+                    expectedCount: expectedAttrKeys.length
+                });
+                // Delete the old table
+                await db.deleteTable({ databaseId, tableId: BACKUP_TABLE_ID });
+                logger.info("Old backup table deleted, will recreate with correct schema");
+            }
+            else {
+                logger.debug("Backup table exists with correct schema", {
+                    tableId: BACKUP_TABLE_ID,
+                    attributeCount: existingAttrKeys.size
+                });
+                return; // Table is good, no need to recreate
+            }
+        }
+        catch (error) {
+            // Error checking table - continue to create
+            logger.debug("Error checking existing table, will attempt to create", {
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    // Create table (either first time or after deletion)
+    logger.info("Creating centralized backup tracking table", {
+        databaseId,
+        tableId: BACKUP_TABLE_ID
+    });
+    await tryAwaitWithRetry(async () => {
+        await db.createTable({
+            databaseId,
+            id: BACKUP_TABLE_ID,
+            name: BACKUP_TABLE_NAME,
+            permissions: [],
+            documentSecurity: false,
+            enabled: true
+        });
+    });
+    // Define all attributes for the enhanced schema
+    const attributes = [
+        // Core backup info
+        { key: "backupType", type: "enum", elements: ["database", "bucket", "comprehensive"], required: true },
+        { key: "backupId", type: "string", size: 50, required: true },
+        { key: "manifestFileId", type: "string", size: 50, required: false },
+        { key: "format", type: "enum", elements: ["json", "zip"], required: true },
+        { key: "sizeBytes", type: "integer", required: true },
+        // Resource identification (optional, at least one present based on type)
+        { key: "databaseId", type: "string", size: 50, required: false },
+        { key: "bucketId", type: "string", size: 50, required: false },
+        { key: "comprehensiveBackupId", type: "string", size: 50, required: false },
+        // Database-specific metrics
+        { key: "collections", type: "integer", required: false },
+        { key: "documents", type: "integer", required: false },
+        // Bucket-specific metrics
+        { key: "fileCount", type: "integer", required: false },
+        // Status tracking
+        { key: "status", type: "enum", elements: ["completed", "partial", "failed"], required: true },
+        { key: "error", type: "string", size: 1000, required: false },
+        // Restoration tracking
+        { key: "restoredAt", type: "string", size: 50, required: false },
+        { key: "restorationStatus", type: "enum", elements: ["completed", "partial", "failed", "not_restored"], required: false },
+        { key: "restorationError", type: "string", size: 1000, required: false }
+    ];
+    // Create each attribute with retry logic
+    // No need to check for existing attributes - table is freshly created or validated above
+    for (const attr of attributes) {
+        await tryAwaitWithRetry(async () => {
+            await db.createAttribute({
+                databaseId,
+                tableId: BACKUP_TABLE_ID,
+                ...attr
+            });
+        });
+    }
+    logger.info("Centralized backup tracking table created successfully", {
+        databaseId,
+        tableId: BACKUP_TABLE_ID,
+        attributeCount: attributes.length
+    });
+}
+/**
+ * Records backup metadata in the centralized tracking table
+ */
+export async function recordCentralizedBackup(db, trackingDatabaseId, metadata) {
+    // Ensure tracking table exists with correct schema
+    await createCentralizedBackupTrackingTable(db, trackingDatabaseId);
+    // Create backup record with all fields
+    // Table is guaranteed to have all attributes after createCentralizedBackupTrackingTable
+    const result = await db.createRow({
+        databaseId: trackingDatabaseId,
+        tableId: BACKUP_TABLE_ID,
+        id: ID.unique(),
+        data: {
+            // Core fields
+            backupType: metadata.backupType,
+            backupId: metadata.backupId,
+            manifestFileId: metadata.manifestFileId || null,
+            format: metadata.format,
+            sizeBytes: metadata.sizeBytes,
+            // Resource identification
+            databaseId: metadata.databaseId || null,
+            bucketId: metadata.bucketId || null,
+            comprehensiveBackupId: metadata.comprehensiveBackupId || null,
+            // Metrics
+            collections: metadata.collections || null,
+            documents: metadata.documents || null,
+            fileCount: metadata.fileCount || null,
+            // Status
+            status: metadata.status,
+            error: metadata.error || null,
+            // Restoration
+            restoredAt: metadata.restoredAt || null,
+            restorationStatus: metadata.restorationStatus || 'not_restored',
+            restorationError: metadata.restorationError || null
+        }
+    });
+    logger.info("Recorded centralized backup metadata", {
+        backupType: metadata.backupType,
+        backupId: metadata.backupId,
+        trackingDatabaseId
+    });
+    return result.data;
+}
+/**
+ * Lists all backups of a specific type, sorted by creation date (newest first)
+ */
+export async function listCentralizedBackups(db, trackingDatabaseId, options) {
+    try {
+        const queries = [
+            Query.orderDesc("$createdAt"),
+            Query.limit(options?.limit || 100)
+        ];
+        // Filter by backup type if specified
+        if (options?.backupType) {
+            queries.push(Query.equal("backupType", options.backupType));
+        }
+        // Filter by resource ID if specified
+        if (options?.resourceId) {
+            if (options.backupType === 'database') {
+                queries.push(Query.equal("databaseId", options.resourceId));
+            }
+            else if (options.backupType === 'bucket') {
+                queries.push(Query.equal("bucketId", options.resourceId));
+            }
+        }
+        const result = await db.listRows({
+            databaseId: trackingDatabaseId,
+            tableId: BACKUP_TABLE_ID,
+            queries
+        });
+        return (result.rows || []);
+    }
+    catch (error) {
+        logger.debug("No centralized backup tracking table found", { trackingDatabaseId });
+        return [];
+    }
+}
+/**
+ * Gets a specific backup by its backup file ID
+ */
+export async function getCentralizedBackup(db, trackingDatabaseId, backupId) {
+    try {
+        const result = await db.listRows({
+            databaseId: trackingDatabaseId,
+            tableId: BACKUP_TABLE_ID,
+            queries: [
+                Query.equal("backupId", backupId),
+                Query.limit(1)
+            ]
+        });
+        if (result.rows && result.rows.length > 0) {
+            return result.rows[0];
+        }
+        return null;
+    }
+    catch (error) {
+        logger.debug("Backup not found", { backupId, trackingDatabaseId });
+        return null;
+    }
+}
+/**
+ * Updates restoration status for a backup
+ */
+export async function updateRestorationStatus(db, trackingDatabaseId, backupRecordId, restorationData) {
+    await db.updateRow({
+        databaseId: trackingDatabaseId,
+        tableId: BACKUP_TABLE_ID,
+        id: backupRecordId,
+        data: {
+            restoredAt: restorationData.restoredAt,
+            restorationStatus: restorationData.restorationStatus,
+            restorationError: restorationData.restorationError || null
+        }
+    });
+    logger.info("Updated restoration status", {
+        backupRecordId,
+        restorationStatus: restorationData.restorationStatus
+    });
+}
+/**
+ * Gets the most recent comprehensive backup
+ */
+export async function getLastComprehensiveBackup(db, trackingDatabaseId) {
+    try {
+        const result = await db.listRows({
+            databaseId: trackingDatabaseId,
+            tableId: BACKUP_TABLE_ID,
+            queries: [
+                Query.equal("backupType", "comprehensive"),
+                Query.orderDesc("$createdAt"),
+                Query.limit(1)
+            ]
+        });
+        if (result.rows && result.rows.length > 0) {
+            return result.rows[0];
+        }
+        return null;
+    }
+    catch (error) {
+        logger.debug("No comprehensive backup found", { trackingDatabaseId });
+        return null;
+    }
+}

package/dist/cli/commands/configCommands.d.ts

@@ -0,0 +1,8 @@
+import type { InteractiveCLI } from "../../interactiveCLI.js";
+export declare const configCommands: {
+    migrateTypeScriptConfig(cli: InteractiveCLI): Promise<void>;
+    validateConfiguration(cli: InteractiveCLI): Promise<void>;
+    migrateCollectionsToTables(cli: InteractiveCLI): Promise<void>;
+    createCollectionConfig(cli: InteractiveCLI): Promise<void>;
+    reloadConfigWithSessionPreservation(cli: InteractiveCLI): Promise<void>;
+};

package/dist/cli/commands/configCommands.js

@@ -0,0 +1,160 @@
+import inquirer from "inquirer";
+import { MessageFormatter } from "../../shared/messageFormatter.js";
+import { migrateConfig } from "../../utils/configMigration.js";
+import { validateCollectionsTablesConfig, reportValidationResults, } from "../../config/configValidation.js";
+import { createMigrationPlan, executeMigrationPlan, saveMigrationResult, } from "../../config/configMigration.js";
+import { createEmptyCollection } from "../../utils/setupFiles.js";
+import chalk from "chalk";
+export const configCommands = {
+    async migrateTypeScriptConfig(cli) {
+        try {
+            MessageFormatter.info("Starting TypeScript to YAML configuration migration...", { prefix: "Migration" });
+            // Perform the migration
+            await migrateConfig(cli.currentDir);
+            // Reset the detection flag
+            cli.isUsingTypeScriptConfig = false;
+            // Reset the controller to pick up the new config
+            cli.controller = undefined;
+            MessageFormatter.success("Migration completed successfully!", { prefix: "Migration" });
+            MessageFormatter.info("Your configuration has been migrated to the .appwrite directory structure", { prefix: "Migration" });
+            MessageFormatter.info("You can now use YAML configuration for easier management", { prefix: "Migration" });
+        }
+        catch (error) {
+            MessageFormatter.error("Migration failed", error instanceof Error ? error : new Error(String(error)), { prefix: "Migration" });
+        }
+    },
+    async validateConfiguration(cli) {
+        try {
+            MessageFormatter.info("Starting configuration validation...", { prefix: "Validation" });
+            await cli.initControllerIfNeeded();
+            const config = cli.controller?.config;
+            if (!config) {
+                MessageFormatter.error("No configuration found to validate", undefined, { prefix: "Validation" });
+                return;
+            }
+            const { validateCollectionsTablesConfig, reportValidationResults } = await import("../../config/configValidation.js");
+            const validation = validateCollectionsTablesConfig(config);
+            reportValidationResults(validation, { verbose: true });
+            if (validation.isValid) {
+                MessageFormatter.success("Configuration validation passed!", { prefix: "Validation" });
+            }
+            else {
+                MessageFormatter.error("Configuration validation failed", undefined, { prefix: "Validation" });
+            }
+        }
+        catch (error) {
+            MessageFormatter.error("Validation failed", error instanceof Error ? error : new Error(String(error)), { prefix: "Validation" });
+        }
+    },
+    async migrateCollectionsToTables(cli) {
+        try {
+            MessageFormatter.info("Starting collections to tables migration...", { prefix: "Migration" });
+            await cli.initControllerIfNeeded();
+            // Ensure config is properly loaded with YAML collections
+            if (!cli.controller?.config) {
+                MessageFormatter.error("No configuration found", undefined, { prefix: "Migration" });
+                return;
+            }
+            // Check if collections exist
+            if (!cli.controller.config.collections || cli.controller.config.collections.length === 0) {
+                MessageFormatter.error("No collections found in configuration. Please check your YAML files or appwriteConfig.ts", undefined, { prefix: "Migration" });
+                return;
+            }
+            const { createMigrationPlan, executeMigrationPlan, saveMigrationResult } = await import("../../config/configMigration.js");
+            // Get user's migration strategy preference
+            const { strategy } = await inquirer.prompt([
+                {
+                    type: "list",
+                    name: "strategy",
+                    message: "Choose migration strategy:",
+                    choices: [
+                        { name: "Move files (rename collections/ to tables/)", value: "move" },
+                        { name: "Copy files (keep both collections/ and tables/)", value: "copy" },
+                        { name: "Dual format (create both .ts and .yaml versions)", value: "dual" }
+                    ]
+                }
+            ]);
+            // Map user-friendly strategy names to internal MigrationStrategy types
+            const migrationStrategy = strategy === "move" ? "full_migration" :
+                strategy === "copy" || strategy === "dual" ? "dual_format" : "full_migration";
+            const plan = createMigrationPlan(cli.controller.config, migrationStrategy);
+            const { confirmed } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "confirmed",
+                    message: `Proceed with migration? This will affect ${plan.collectionsToMigrate?.length || 0} files.`,
+                    default: false
+                }
+            ]);
+            if (confirmed) {
+                const result = executeMigrationPlan(cli.controller.config, plan);
+                await saveMigrationResult(result, cli.currentDir);
+                MessageFormatter.success("Collections to tables migration completed!", { prefix: "Migration" });
+            }
+            else {
+                MessageFormatter.info("Migration cancelled by user", { prefix: "Migration" });
+            }
+        }
+        catch (error) {
+            MessageFormatter.error("Migration failed", error instanceof Error ? error : new Error(String(error)), { prefix: "Migration" });
+        }
+    },
+    async createCollectionConfig(cli) {
+        const { collectionName } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "collectionName",
+                message: chalk.blue("Enter the name of the collection:"),
+                validate: (input) => input.trim() !== "" || "Collection name cannot be empty.",
+            },
+        ]);
+        MessageFormatter.progress(`Creating collection config file for '${collectionName}'...`, { prefix: "Collections" });
+        createEmptyCollection(collectionName);
+        MessageFormatter.success(`Collection config file created for '${collectionName}'`, { prefix: "Collections" });
+    },
+    async reloadConfigWithSessionPreservation(cli) {
+        MessageFormatter.progress("Reloading configuration files with session preservation...", { prefix: "Config" });
+        try {
+            const controller = cli.controller;
+            const UtilsController = (await import("../../utilsController.js")).UtilsController;
+            if (controller) {
+                const sessionInfo = controller.getSessionInfo();
+                if (sessionInfo.hasSession) {
+                    // Extract session details for preservation
+                    const sessionData = {
+                        sessionCookie: controller.sessionCookie,
+                        sessionMetadata: controller.sessionMetadata
+                    };
+                    // Store current config values for potential directConfig creation
+                    const currentConfig = controller.config;
+                    let directConfig = undefined;
+                    if (currentConfig?.appwriteEndpoint && currentConfig?.appwriteProject) {
+                        directConfig = {
+                            appwriteEndpoint: currentConfig.appwriteEndpoint,
+                            appwriteProject: currentConfig.appwriteProject,
+                            appwriteKey: currentConfig.appwriteKey,
+                            ...sessionData // Preserve session
+                        };
+                    }
+                    // Reinitialize controller with session preservation
+                    cli.controller = new UtilsController(cli.currentDir, directConfig);
+                    await cli.controller.init();
+                    MessageFormatter.success("Configuration reloaded with session preserved", { prefix: "Config" });
+                }
+                else {
+                    // No session to preserve, standard reload
+                    await controller.reloadConfig();
+                    MessageFormatter.success("Configuration files reloaded successfully", { prefix: "Config" });
+                }
+            }
+            else {
+                // Initialize if no controller exists
+                await cli.initControllerIfNeeded();
+                MessageFormatter.success("Configuration initialized successfully", { prefix: "Config" });
+            }
+        }
+        catch (error) {
+            MessageFormatter.error("Failed to reload configuration files", error instanceof Error ? error : new Error(String(error)), { prefix: "Config" });
+        }
+    }
+};

package/dist/cli/commands/databaseCommands.d.ts

@@ -0,0 +1,13 @@
+import type { InteractiveCLI } from "../../interactiveCLI.js";
+export declare const databaseCommands: {
+    syncDb(cli: InteractiveCLI): Promise<void>;
+    synchronizeConfigurations(cli: InteractiveCLI): Promise<void>;
+    backupDatabase(cli: InteractiveCLI): Promise<void>;
+    selectTrackingDatabase(cli: InteractiveCLI): Promise<string>;
+    ensureBackupTrackingTable(cli: InteractiveCLI, trackingDatabaseId: string): Promise<void>;
+    selectBackupScope(cli: InteractiveCLI): Promise<any>;
+    confirmBackupPlan(scope: any): Promise<boolean>;
+    executeUnifiedBackup(cli: InteractiveCLI, trackingDatabaseId: string, scope: any): Promise<void>;
+    wipeDatabase(cli: InteractiveCLI): Promise<void>;
+    wipeCollections(cli: InteractiveCLI): Promise<void>;
+};