appwrite-utils-cli 1.11.0 → 1.12.0

package/dist/shared/selectionDialogs.js

@@ -0,0 +1,588 @@
+import inquirer from "inquirer";
+import chalk from "chalk";
+import { MessageFormatter } from 'appwrite-utils-helpers';
+import { logger } from 'appwrite-utils-helpers';
+/**
+ * Comprehensive selection dialog system for enhanced sync flow
+ *
+ * This class provides interactive dialogs for selecting databases, tables/collections,
+ * and storage buckets during sync operations. It supports both new and existing
+ * configurations with visual indicators and comprehensive confirmation flows.
+ *
+ * @example
+ * ```typescript
+ * import { SelectionDialogs } from './shared/selectionDialogs.js';
+ * import type { Models } from 'node-appwrite';
+ *
+ * // Example usage in a sync command
+ * const availableDatabases: Models.Database[] = await getAvailableDatabases();
+ * const configuredDatabases = config.databases || [];
+ *
+ * // Prompt about existing configuration
+ * const { syncExisting, modifyConfiguration } = await SelectionDialogs.promptForExistingConfig(configuredDatabases);
+ *
+ * if (modifyConfiguration) {
+ *   // Select databases
+ *   const selectedDatabaseIds = await SelectionDialogs.selectDatabases(
+ *     availableDatabases,
+ *     configuredDatabases,
+ *     { showSelectAll: true, allowNewOnly: !syncExisting }
+ *   );
+ *
+ *   // For each database, select tables
+ *   const tableSelectionsMap = new Map<string, string[]>();
+ *   const availableTablesMap = new Map<string, any[]>();
+ *
+ *   for (const databaseId of selectedDatabaseIds) {
+ *     const database = availableDatabases.find(db => db.$id === databaseId)!;
+ *     const availableTables = await getTablesForDatabase(databaseId);
+ *     const configuredTables = getConfiguredTablesForDatabase(databaseId);
+ *
+ *     availableTablesMap.set(databaseId, availableTables);
+ *
+ *     const selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
+ *       databaseId,
+ *       database.name,
+ *       availableTables,
+ *       configuredTables,
+ *       { showSelectAll: true, allowNewOnly: !syncExisting }
+ *     );
+ *
+ *     tableSelectionsMap.set(databaseId, selectedTableIds);
+ *   }
+ *
+ *   // Select buckets
+ *   const availableBuckets = await getAvailableBuckets();
+ *   const configuredBuckets = config.buckets || [];
+ *   const selectedBucketIds = await SelectionDialogs.selectBucketsForDatabases(
+ *     selectedDatabaseIds,
+ *     availableBuckets,
+ *     configuredBuckets,
+ *     { showSelectAll: true, groupByDatabase: true }
+ *   );
+ *
+ *   // Create selection objects
+ *   const databaseSelections = SelectionDialogs.createDatabaseSelection(
+ *     selectedDatabaseIds,
+ *     availableDatabases,
+ *     tableSelectionsMap,
+ *     configuredDatabases,
+ *     availableTablesMap
+ *   );
+ *
+ *   const bucketSelections = SelectionDialogs.createBucketSelection(
+ *     selectedBucketIds,
+ *     availableBuckets,
+ *     configuredBuckets,
+ *     availableDatabases
+ *   );
+ *
+ *   // Show final confirmation
+ *   const selectionSummary = SelectionDialogs.createSyncSelectionSummary(
+ *     databaseSelections,
+ *     bucketSelections
+ *   );
+ *
+ *   const confirmed = await SelectionDialogs.confirmSyncSelection(selectionSummary);
+ *
+ *   if (confirmed) {
+ *     // Proceed with sync operation
+ *     await performSync(databaseSelections, bucketSelections);
+ *   }
+ * }
+ * ```
+ */
+export class SelectionDialogs {
+    /**
+     * Prompts user about existing configuration
+     */
+    static async promptForExistingConfig(configuredItems) {
+        if (configuredItems.length === 0) {
+            return { syncExisting: false, modifyConfiguration: true };
+        }
+        MessageFormatter.section("Existing Configuration Found");
+        MessageFormatter.info(`Found ${configuredItems.length} configured items.`, { skipLogging: true });
+        const { syncExisting } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'syncExisting',
+                message: 'Sync existing configured items?',
+                default: true
+            }]);
+        if (!syncExisting) {
+            return { syncExisting: false, modifyConfiguration: true };
+        }
+        const { modifyConfiguration } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'modifyConfiguration',
+                message: 'Add/remove items from configuration?',
+                default: false
+            }]);
+        return { syncExisting, modifyConfiguration };
+    }
+    /**
+     * Shows database selection dialog with indicators for configured vs new databases
+     */
+    static async selectDatabases(availableDatabases, configuredDatabases, options = {}) {
+        const { showSelectAll = true, allowNewOnly = false, defaultSelected = [] } = options;
+        MessageFormatter.section("Database Selection");
+        const configuredIds = new Set(configuredDatabases.map(db => db.$id || db.id));
+        let choices = [];
+        if (showSelectAll && availableDatabases.length > 1) {
+            choices.push({
+                name: chalk.green.bold('📋 Select All Databases'),
+                value: '__SELECT_ALL__',
+                short: 'All databases'
+            });
+        }
+        availableDatabases.forEach(database => {
+            const isConfigured = configuredIds.has(database.$id);
+            const status = isConfigured ? chalk.green('✅') : chalk.blue('○');
+            const name = `${status} ${database.name} (${database.$id})`;
+            if (allowNewOnly && isConfigured) {
+                return; // Skip configured databases if only allowing new ones
+            }
+            choices.push({
+                name,
+                value: database.$id,
+                short: database.name,
+                // Do not preselect anything unless explicitly provided
+                checked: defaultSelected.includes(database.$id)
+            });
+        });
+        if (choices.length === 0) {
+            MessageFormatter.warning("No databases available for selection.", { skipLogging: true });
+            return [];
+        }
+        const { selectedDatabaseIds } = await inquirer.prompt([{
+                type: 'checkbox',
+                name: 'selectedDatabaseIds',
+                message: 'Select databases to sync:',
+                choices,
+                validate: (input) => {
+                    if (input.length === 0) {
+                        return chalk.red('Please select at least one database.');
+                    }
+                    if (input.includes('__SELECT_ALL__') && input.length > 1) {
+                        return chalk.red('Cannot select "Select All" with individual databases.');
+                    }
+                    return true;
+                }
+            }]);
+        // Handle select all
+        if (selectedDatabaseIds.includes('__SELECT_ALL__')) {
+            const allIds = availableDatabases.map(db => db.$id);
+            if (allowNewOnly) {
+                return allIds.filter(id => !configuredIds.has(id));
+            }
+            return allIds;
+        }
+        return selectedDatabaseIds;
+    }
+    /**
+     * Shows table/collection selection dialog for a specific database
+     */
+    static async selectTablesForDatabase(databaseId, databaseName, availableTables, configuredTables, options = {}) {
+        const { showSelectAll = true, allowNewOnly = false, defaultSelected = [], showDatabaseContext = true } = options;
+        if (showDatabaseContext) {
+            MessageFormatter.section(`Table Selection for ${databaseName}`);
+        }
+        const configuredIds = new Set(configuredTables.map(table => table.$id || table.id || table.tableId || table.name));
+        let choices = [];
+        if (showSelectAll && availableTables.length > 1) {
+            choices.push({
+                name: chalk.green.bold('📋 Select All Tables'),
+                value: '__SELECT_ALL__',
+                short: 'All tables'
+            });
+        }
+        availableTables.forEach(table => {
+            const tableId = table.$id || table.id || table.tableId || table.name;
+            const isConfigured = configuredIds.has(tableId);
+            const status = isConfigured ? chalk.green('✅') : chalk.blue('○');
+            const name = `${status} ${table.name} (${tableId})`;
+            if (allowNewOnly && isConfigured) {
+                return; // Skip configured tables if only allowing new ones
+            }
+            choices.push({
+                name,
+                value: tableId,
+                short: table.name,
+                // Do not preselect anything unless explicitly provided
+                checked: defaultSelected.includes(tableId)
+            });
+        });
+        if (choices.length === 0) {
+            MessageFormatter.warning(`No tables available for database: ${databaseName}`, { skipLogging: true });
+            return [];
+        }
+        const { selectedTableIds } = await inquirer.prompt([{
+                type: 'checkbox',
+                name: 'selectedTableIds',
+                message: `Select tables to sync for ${databaseName}:`,
+                choices,
+                validate: (input) => {
+                    if (input.length === 0) {
+                        return chalk.red('Please select at least one table.');
+                    }
+                    if (input.includes('__SELECT_ALL__') && input.length > 1) {
+                        return chalk.red('Cannot select "Select All" with individual tables.');
+                    }
+                    return true;
+                }
+            }]);
+        // Handle select all
+        if (selectedTableIds.includes('__SELECT_ALL__')) {
+            const allIds = availableTables.map(table => table.$id || table.id || table.tableId || table.name);
+            if (allowNewOnly) {
+                return allIds.filter(id => !configuredIds.has(id));
+            }
+            return allIds;
+        }
+        return selectedTableIds;
+    }
+    /**
+     * Shows bucket selection dialog for selected databases
+     */
+    static async selectBucketsForDatabases(selectedDatabaseIds, availableBuckets, configuredBuckets, options = {}) {
+        const { showSelectAll = true, allowNewOnly = false, defaultSelected = [], groupByDatabase = true } = options;
+        MessageFormatter.section("Storage Bucket Selection");
+        const configuredIds = new Set(configuredBuckets.map(bucket => bucket.$id || bucket.id));
+        // Filter buckets that are associated with selected databases
+        const relevantBuckets = availableBuckets.filter(bucket => {
+            if (selectedDatabaseIds.length === 0)
+                return true; // If no databases selected, show all buckets
+            return selectedDatabaseIds.includes(bucket.databaseId) || !bucket.databaseId;
+        });
+        if (relevantBuckets.length === 0) {
+            MessageFormatter.warning("No storage buckets available for selected databases.", { skipLogging: true });
+            return [];
+        }
+        let choices = [];
+        if (showSelectAll && relevantBuckets.length > 1) {
+            choices.push({
+                name: chalk.green.bold('📋 Select All Buckets'),
+                value: '__SELECT_ALL__',
+                short: 'All buckets'
+            });
+        }
+        if (groupByDatabase) {
+            // Group buckets by database
+            const bucketsByDatabase = new Map();
+            relevantBuckets.forEach(bucket => {
+                const dbId = bucket.databaseId || 'ungrouped';
+                if (!bucketsByDatabase.has(dbId)) {
+                    bucketsByDatabase.set(dbId, []);
+                }
+                bucketsByDatabase.get(dbId).push(bucket);
+            });
+            // Add buckets grouped by database
+            selectedDatabaseIds.forEach(dbId => {
+                const buckets = bucketsByDatabase.get(dbId) || [];
+                if (buckets.length > 0) {
+                    choices.push(new inquirer.Separator(chalk.cyan(`📁 Database: ${dbId}`)));
+                    buckets.forEach(bucket => {
+                        const isConfigured = configuredIds.has(bucket.$id);
+                        const status = isConfigured ? chalk.green('✅') : chalk.blue('○');
+                        const name = `${status} ${bucket.name} (${bucket.$id})`;
+                        if (allowNewOnly && isConfigured) {
+                            return; // Skip configured buckets if only allowing new ones
+                        }
+                        choices.push({
+                            name: `  ${name}`,
+                            value: bucket.$id,
+                            short: bucket.name,
+                            // Do not preselect anything unless explicitly provided
+                            checked: defaultSelected.includes(bucket.$id)
+                        });
+                    });
+                }
+            });
+            // Add ungrouped buckets
+            const ungroupedBuckets = bucketsByDatabase.get('ungrouped') || [];
+            if (ungroupedBuckets.length > 0) {
+                choices.push(new inquirer.Separator(chalk.cyan('📁 General Storage')));
+                ungroupedBuckets.forEach(bucket => {
+                    const isConfigured = configuredIds.has(bucket.$id);
+                    const status = isConfigured ? chalk.green('✅') : chalk.blue('○');
+                    const name = `${status} ${bucket.name} (${bucket.$id})`;
+                    if (allowNewOnly && isConfigured) {
+                        return; // Skip configured buckets if only allowing new ones
+                    }
+                    choices.push({
+                        name: `  ${name}`,
+                        value: bucket.$id,
+                        short: bucket.name,
+                        checked: defaultSelected.includes(bucket.$id) || (!allowNewOnly && isConfigured)
+                    });
+                });
+            }
+        }
+        else {
+            // Flat list of buckets
+            relevantBuckets.forEach(bucket => {
+                const isConfigured = configuredIds.has(bucket.$id);
+                const status = isConfigured ? chalk.green('✅') : chalk.blue('○');
+                const dbContext = bucket.databaseId ? ` [${bucket.databaseId}]` : '';
+                const name = `${status} ${bucket.name} (${bucket.$id})${dbContext}`;
+                if (allowNewOnly && isConfigured) {
+                    return; // Skip configured buckets if only allowing new ones
+                }
+                choices.push({
+                    name,
+                    value: bucket.$id,
+                    short: bucket.name,
+                    // Do not preselect anything unless explicitly provided
+                    checked: defaultSelected.includes(bucket.$id)
+                });
+            });
+        }
+        const { selectedBucketIds } = await inquirer.prompt([{
+                type: 'checkbox',
+                name: 'selectedBucketIds',
+                message: 'Select storage buckets to sync:',
+                choices,
+                validate: (input) => {
+                    if (input.length === 0) {
+                        return chalk.yellow('No storage buckets selected. Continue with databases only?') || true;
+                    }
+                    if (input.includes('__SELECT_ALL__') && input.length > 1) {
+                        return chalk.red('Cannot select "Select All" with individual buckets.');
+                    }
+                    return true;
+                }
+            }]);
+        // Handle select all
+        if (selectedBucketIds && selectedBucketIds.includes('__SELECT_ALL__')) {
+            const allIds = relevantBuckets.map(bucket => bucket.$id);
+            if (allowNewOnly) {
+                return allIds.filter(id => !configuredIds.has(id));
+            }
+            return allIds;
+        }
+        return selectedBucketIds || [];
+    }
+    /**
+     * Shows bucket selection for push operations with merged local+remote buckets.
+     * Unlike selectBucketsForDatabases, this shows all buckets as a flat list
+     * with source indicators (Local only, Remote only, Configured).
+     */
+    static async selectBucketsForPush(mergedBuckets, configuredBuckets, options = {}) {
+        MessageFormatter.section("Storage Bucket Selection");
+        if (mergedBuckets.length === 0) {
+            MessageFormatter.warning("No storage buckets found (local or remote).", { skipLogging: true });
+            return [];
+        }
+        const choices = mergedBuckets.map(bucket => {
+            let status;
+            let suffix = '';
+            if (bucket._isLocalOnly) {
+                status = chalk.yellow('*');
+                suffix = chalk.yellow(' (Local only - will be created)');
+            }
+            else if (bucket._isRemoteOnly) {
+                status = chalk.blue('○');
+                suffix = chalk.blue(' (Remote only)');
+            }
+            else {
+                status = chalk.green('✅');
+                suffix = chalk.green(' (Configured)');
+            }
+            return {
+                name: `${status} ${bucket.name} (${bucket.$id})${suffix}`,
+                value: bucket.$id,
+                short: bucket.name,
+            };
+        });
+        const { selectedBucketIds } = await inquirer.prompt([{
+                type: 'checkbox',
+                name: 'selectedBucketIds',
+                message: 'Select storage buckets to push:',
+                choices,
+            }]);
+        return selectedBucketIds || [];
+    }
+    /**
+     * Shows final confirmation dialog with sync selection summary
+     */
+    static async confirmSyncSelection(selectionSummary, operationType = 'sync') {
+        const labels = {
+            push: {
+                banner: "Push Selection Summary",
+                subtitle: "Review selections before pushing to Appwrite",
+                confirm: "Proceed with push operation?",
+                success: "Push operation confirmed.",
+                cancel: "Push operation cancelled."
+            },
+            pull: {
+                banner: "Pull Selection Summary",
+                subtitle: "Review selections before pulling from Appwrite",
+                confirm: "Proceed with pull operation?",
+                success: "Pull operation confirmed.",
+                cancel: "Pull operation cancelled."
+            },
+            sync: {
+                banner: "Sync Selection Summary",
+                subtitle: "Review your selections before proceeding",
+                confirm: "Proceed with sync operation?",
+                success: "Sync operation confirmed.",
+                cancel: "Sync operation cancelled."
+            }
+        };
+        const label = labels[operationType];
+        MessageFormatter.banner(label.banner, label.subtitle);
+        // Database summary
+        console.log(chalk.bold.cyan("\n📊 Databases:"));
+        console.log(`  Total: ${selectionSummary.totalDatabases}`);
+        console.log(`  ${chalk.green('✅ Configured')}: ${selectionSummary.existingItems.databases}`);
+        console.log(`  ${chalk.blue('○ New')}: ${selectionSummary.newItems.databases}`);
+        if (selectionSummary.databases.length > 0) {
+            console.log(chalk.gray("\n  Selected databases:"));
+            selectionSummary.databases.forEach(db => {
+                const status = db.isNew ? chalk.blue('○') : chalk.green('✅');
+                console.log(`    ${status} ${db.databaseName} (${db.tableNames.length} tables)`);
+            });
+        }
+        // Table summary
+        console.log(chalk.bold.cyan("\n📋 Tables:"));
+        console.log(`  Total: ${selectionSummary.totalTables}`);
+        console.log(`  ${chalk.green('✅ Configured')}: ${selectionSummary.existingItems.tables}`);
+        console.log(`  ${chalk.blue('○ New')}: ${selectionSummary.newItems.tables}`);
+        // Bucket summary
+        console.log(chalk.bold.cyan("\n🪣 Storage Buckets:"));
+        console.log(`  Total: ${selectionSummary.totalBuckets}`);
+        console.log(`  ${chalk.green('✅ Configured')}: ${selectionSummary.existingItems.buckets}`);
+        console.log(`  ${chalk.blue('○ New')}: ${selectionSummary.newItems.buckets}`);
+        if (selectionSummary.buckets.length > 0) {
+            console.log(chalk.gray("\n  Selected buckets:"));
+            selectionSummary.buckets.forEach(bucket => {
+                const status = bucket.isNew ? chalk.blue('○') : chalk.green('✅');
+                const dbContext = bucket.databaseName ? ` [${bucket.databaseName}]` : '';
+                console.log(`    ${status} ${bucket.bucketName}${dbContext}`);
+            });
+        }
+        console.log(); // Add spacing
+        const { confirmed } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'confirmed',
+                message: chalk.green.bold(label.confirm),
+                default: true
+            }]);
+        if (confirmed) {
+            MessageFormatter.success(label.success, { skipLogging: true });
+            logger.info(`${operationType} selection confirmed`, {
+                databases: selectionSummary.totalDatabases,
+                tables: selectionSummary.totalTables,
+                buckets: selectionSummary.totalBuckets
+            });
+        }
+        else {
+            MessageFormatter.warning(label.cancel, { skipLogging: true });
+            logger.info(`${operationType} selection cancelled by user`);
+        }
+        return confirmed;
+    }
+    /**
+     * Creates a sync selection summary from selected items
+     */
+    static createSyncSelectionSummary(databaseSelections, bucketSelections) {
+        const totalDatabases = databaseSelections.length;
+        const totalTables = databaseSelections.reduce((sum, db) => sum + db.tableIds.length, 0);
+        const totalBuckets = bucketSelections.length;
+        const newDatabases = databaseSelections.filter(db => db.isNew).length;
+        const newTables = databaseSelections.reduce((sum, db) => sum + db.tableIds.length, 0); // TODO: Track which tables are new
+        const newBuckets = bucketSelections.filter(bucket => bucket.isNew).length;
+        const existingDatabases = totalDatabases - newDatabases;
+        const existingTables = totalTables - newTables;
+        const existingBuckets = totalBuckets - newBuckets;
+        return {
+            databases: databaseSelections,
+            buckets: bucketSelections,
+            totalDatabases,
+            totalTables,
+            totalBuckets,
+            newItems: {
+                databases: newDatabases,
+                tables: newTables,
+                buckets: newBuckets
+            },
+            existingItems: {
+                databases: existingDatabases,
+                tables: existingTables,
+                buckets: existingBuckets
+            }
+        };
+    }
+    /**
+     * Helper method to create database selection objects
+     */
+    static createDatabaseSelection(selectedDatabaseIds, availableDatabases, tableSelectionsMap, configuredDatabases, availableTablesMap = new Map()) {
+        const configuredIds = new Set(configuredDatabases.map(db => db.$id || db.id));
+        return selectedDatabaseIds.map(databaseId => {
+            const database = availableDatabases.find(db => db.$id === databaseId);
+            if (!database) {
+                throw new Error(`Database with ID ${databaseId} not found in available databases`);
+            }
+            const tableIds = tableSelectionsMap.get(databaseId) || [];
+            const tables = availableTablesMap.get(databaseId) || [];
+            const tableNames = tables.map(table => table.name || table.$id || `Table-${table.$id}`);
+            return {
+                databaseId,
+                databaseName: database.name,
+                tableIds,
+                tableNames,
+                isNew: !configuredIds.has(databaseId)
+            };
+        });
+    }
+    /**
+     * Helper method to create bucket selection objects
+     */
+    static createBucketSelection(selectedBucketIds, availableBuckets, configuredBuckets, availableDatabases) {
+        const configuredIds = new Set(configuredBuckets.map(bucket => bucket.$id || bucket.id));
+        return selectedBucketIds.map(bucketId => {
+            // Look up in availableBuckets first, then fall back to configuredBuckets
+            // (handles merged lists where local-only buckets may only be in configuredBuckets)
+            const bucket = availableBuckets.find(b => b.$id === bucketId)
+                || configuredBuckets.find(b => (b.$id || b.id) === bucketId);
+            if (!bucket) {
+                throw new Error(`Bucket with ID ${bucketId} not found in available or configured buckets`);
+            }
+            const database = bucket.databaseId ?
+                availableDatabases.find(db => db.$id === bucket.databaseId) : undefined;
+            return {
+                bucketId,
+                bucketName: bucket.name,
+                databaseId: bucket.databaseId,
+                databaseName: database?.name,
+                isNew: bucket._isLocalOnly || !configuredIds.has(bucketId)
+            };
+        });
+    }
+    /**
+     * Shows a progress message during selection operations
+     */
+    static showProgress(message) {
+        MessageFormatter.progress(message, { skipLogging: true });
+    }
+    /**
+     * Shows an error message and handles graceful cancellation
+     */
+    static showError(message, error) {
+        MessageFormatter.error(message, error, { skipLogging: true });
+        logger.error(`Selection dialog error: ${message}`, { error: error?.message });
+    }
+    /**
+     * Shows a warning message
+     */
+    static showWarning(message) {
+        MessageFormatter.warning(message, { skipLogging: true });
+        logger.warn(`Selection dialog warning: ${message}`);
+    }
+    /**
+     * Shows a success message
+     */
+    static showSuccess(message) {
+        MessageFormatter.success(message, { skipLogging: true });
+        logger.info(`Selection dialog success: ${message}`);
+    }
+}

package/dist/storage/backupCompression.d.ts

@@ -0,0 +1,20 @@
+import type { BackupCreate } from "./schemas.js";
+export interface BackupCompressionOptions {
+    includeFiles?: boolean;
+    compressionLevel?: number;
+}
+/**
+ * Creates a compressed ZIP backup from backup data
+ *
+ * Structure:
+ * - metadata.json (backup metadata)
+ * - database.json (database config)
+ * - collections/*.json (one file per collection)
+ * - documents/*.json (one file per collection's documents)
+ * - files/ (optional, if includeFiles is true)
+ */
+export declare function createBackupZip(backupData: BackupCreate, options?: BackupCompressionOptions): Promise<Buffer>;
+/**
+ * Estimates compression ratio for backup data
+ */
+export declare function estimateCompressedSize(uncompressedSize: number, format?: string): number;

package/dist/storage/backupCompression.js

@@ -0,0 +1,67 @@
+import JSZip from "jszip";
+/**
+ * Creates a compressed ZIP backup from backup data
+ *
+ * Structure:
+ * - metadata.json (backup metadata)
+ * - database.json (database config)
+ * - collections/*.json (one file per collection)
+ * - documents/*.json (one file per collection's documents)
+ * - files/ (optional, if includeFiles is true)
+ */
+export async function createBackupZip(backupData, options = {}) {
+    const zip = new JSZip();
+    const compressionLevel = options.compressionLevel ?? 6;
+    // Add metadata.json
+    const metadata = {
+        version: "1.0",
+        createdAt: new Date().toISOString(),
+        databaseId: JSON.parse(backupData.database).$id,
+        format: "zip",
+        includesFiles: options.includeFiles ?? false
+    };
+    zip.file("metadata.json", JSON.stringify(metadata, null, 2));
+    // Add database.json
+    zip.file("database.json", backupData.database);
+    // Add collections/*.json
+    const collectionsFolder = zip.folder("collections");
+    if (collectionsFolder) {
+        backupData.collections.forEach((collectionStr, index) => {
+            const collection = JSON.parse(collectionStr);
+            collectionsFolder.file(`${collection.$id || `collection_${index}`}.json`, collectionStr);
+        });
+    }
+    // Add documents/*.json
+    const documentsFolder = zip.folder("documents");
+    if (documentsFolder) {
+        backupData.documents.forEach((docBatch) => {
+            const collectionId = docBatch.collectionId;
+            documentsFolder.file(`${collectionId}.json`, docBatch.data);
+        });
+    }
+    // TODO: Add files support in future task (C3.5)
+    if (options.includeFiles) {
+        // Placeholder for file backup support
+        const filesFolder = zip.folder("files");
+        if (filesFolder) {
+            filesFolder.file("file-manifest.json", JSON.stringify({
+                note: "File backup not yet implemented"
+            }, null, 2));
+        }
+    }
+    // Generate ZIP buffer
+    const buffer = await zip.generateAsync({
+        type: "nodebuffer",
+        compression: "DEFLATE",
+        compressionOptions: { level: compressionLevel }
+    });
+    return buffer;
+}
+/**
+ * Estimates compression ratio for backup data
+ */
+export function estimateCompressedSize(uncompressedSize, format = "json") {
+    // JSON typically compresses to 20-30% of original size with gzip
+    const compressionRatio = format === "json" ? 0.25 : 0.5;
+    return Math.ceil(uncompressedSize * compressionRatio);
+}