appwrite-utils-cli 1.11.0 → 1.12.0

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 "appwrite-utils-helpers";
+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 'appwrite-utils-helpers';
+import { tryAwaitWithRetry } from "appwrite-utils-helpers";
+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.d.ts

@@ -0,0 +1,75 @@
+export interface DestructiveOperationOptions {
+    operation: string;
+    targets: string[];
+    consequences?: string[];
+    requireExplicitConfirmation?: boolean;
+    confirmationText?: string;
+    skipConfirmation?: boolean;
+}
+export interface BackupPromptOptions {
+    operation: string;
+    targets: string[];
+    recommendBackup?: boolean;
+    backupMessage?: string;
+}
+export declare class ConfirmationDialogs {
+    /**
+     * Shows a confirmation dialog for destructive operations
+     */
+    static confirmDestructiveOperation(options: DestructiveOperationOptions): Promise<boolean>;
+    /**
+     * Prompts user about creating a backup before a destructive operation
+     */
+    static promptForBackup(options: BackupPromptOptions): Promise<'yes' | 'no' | 'skip'>;
+    /**
+     * Shows a final confirmation before proceeding with an operation
+     */
+    static finalConfirmation(operation: string, details?: string[]): Promise<boolean>;
+    /**
+     * Specialized confirmation for database wiping
+     */
+    static confirmDatabaseWipe(databaseNames: string[], options?: {
+        includeStorage?: boolean;
+        includeUsers?: boolean;
+        skipConfirmation?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Specialized confirmation for collection wiping
+     */
+    static confirmCollectionWipe(databaseName: string, collectionNames: string[], options?: {
+        skipConfirmation?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Specialized confirmation for function deployment
+     */
+    static confirmFunctionDeployment(functionNames: string[], options?: {
+        isProduction?: boolean;
+        hasBreakingChanges?: boolean;
+        skipConfirmation?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Shows operation summary and asks for final confirmation
+     */
+    static showOperationSummary(title: string, summary: Record<string, string | number | string[]>, options?: {
+        confirmationRequired?: boolean;
+        warningMessage?: string;
+    }): Promise<boolean>;
+    /**
+     * Interactive selection with confirmation
+     */
+    static selectWithConfirmation<T>(items: T[], options: {
+        message: string;
+        displayProperty?: keyof T;
+        multiSelect?: boolean;
+        confirmMessage?: string;
+        validator?: (selection: T[]) => string | true;
+    }): Promise<T[]>;
+    /**
+     * Confirms overwriting an existing file or directory
+     */
+    static confirmOverwrite(target: string): Promise<boolean>;
+    /**
+     * Confirms removal of a file
+     */
+    static confirmRemoval(target: string): Promise<boolean>;
+}

package/dist/shared/confirmationDialogs.js

@@ -0,0 +1,236 @@
+import inquirer from "inquirer";
+import chalk from "chalk";
+import { MessageFormatter } from 'appwrite-utils-helpers';
+export class ConfirmationDialogs {
+    /**
+     * Shows a confirmation dialog for destructive operations
+     */
+    static async confirmDestructiveOperation(options) {
+        if (options.skipConfirmation) {
+            return true;
+        }
+        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) {
+            MessageFormatter.error("This will:", undefined, { skipLogging: true });
+            options.consequences.forEach(consequence => {
+                MessageFormatter.error(`  • ${consequence}`, undefined, { skipLogging: true });
+            });
+        }
+        MessageFormatter.error("⚠️  THIS ACTION CANNOT BE UNDONE!", undefined, { skipLogging: true });
+        if (options.requireExplicitConfirmation && options.confirmationText) {
+            const { confirmation } = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'confirmation',
+                    message: chalk.red(`Type "${options.confirmationText}" to confirm:`),
+                    validate: (input) => {
+                        return input === options.confirmationText ||
+                            chalk.red(`Please type exactly: ${options.confirmationText}`);
+                    }
+                }]);
+            return confirmation === options.confirmationText;
+        }
+        else {
+            const { confirmed } = await inquirer.prompt([{
+                    type: 'confirm',
+                    name: 'confirmed',
+                    message: chalk.red('Are you absolutely sure you want to continue?'),
+                    default: false
+                }]);
+            return confirmed;
+        }
+    }
+    /**
+     * Prompts user about creating a backup before a destructive operation
+     */
+    static async promptForBackup(options) {
+        const message = options.backupMessage ||
+            `Create a backup before performing ${options.operation} on: ${options.targets.join(", ")}?`;
+        MessageFormatter.info("🛡️  Backup Recommendation", { skipLogging: true });
+        if (options.recommendBackup !== false) {
+            MessageFormatter.warning("It's strongly recommended to create a backup before proceeding.", { skipLogging: true });
+        }
+        const { choice } = await inquirer.prompt([{
+                type: 'list',
+                name: 'choice',
+                message,
+                choices: [
+                    { name: '🛡️  Yes, create backup first', value: 'yes' },
+                    { name: '⚠️  No, proceed without backup', value: 'no' },
+                    { name: '❌ Cancel operation', value: 'skip' }
+                ],
+                default: 'yes'
+            }]);
+        return choice;
+    }
+    /**
+     * Shows a final confirmation before proceeding with an operation
+     */
+    static async finalConfirmation(operation, details) {
+        MessageFormatter.success(`Ready to perform: ${operation}`, { skipLogging: true });
+        if (details && details.length > 0) {
+            MessageFormatter.debug("Details:", undefined, { skipLogging: true });
+            details.forEach(detail => {
+                MessageFormatter.debug(`  • ${detail}`, undefined, { skipLogging: true });
+            });
+        }
+        const { proceed } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'proceed',
+                message: 'Proceed with this operation?',
+                default: true
+            }]);
+        return proceed;
+    }
+    /**
+     * Specialized confirmation for database wiping
+     */
+    static async confirmDatabaseWipe(databaseNames, options = {}) {
+        const consequences = [
+            "Delete all documents in the specified databases",
+            "Remove all collections and their data",
+        ];
+        if (options.includeStorage) {
+            consequences.push("Delete all files in associated storage buckets");
+        }
+        if (options.includeUsers) {
+            consequences.push("Delete all user accounts");
+        }
+        return this.confirmDestructiveOperation({
+            operation: "Database Wipe",
+            targets: databaseNames,
+            consequences,
+            requireExplicitConfirmation: true,
+            confirmationText: "DELETE ALL DATA",
+            skipConfirmation: options.skipConfirmation,
+        });
+    }
+    /**
+     * Specialized confirmation for collection wiping
+     */
+    static async confirmCollectionWipe(databaseName, collectionNames, options = {}) {
+        return this.confirmDestructiveOperation({
+            operation: "Collection Wipe",
+            targets: collectionNames.map(name => `${databaseName}.${name}`),
+            consequences: [
+                "Delete all documents in the specified collections",
+                "Keep the collection structure intact",
+            ],
+            requireExplicitConfirmation: collectionNames.length > 5,
+            confirmationText: "DELETE DOCUMENTS",
+            skipConfirmation: options.skipConfirmation,
+        });
+    }
+    /**
+     * Specialized confirmation for function deployment
+     */
+    static async confirmFunctionDeployment(functionNames, options = {}) {
+        if (options.skipConfirmation) {
+            return true;
+        }
+        const consequences = ["Replace existing function code"];
+        if (options.isProduction) {
+            consequences.push("Affect production environment");
+        }
+        if (options.hasBreakingChanges) {
+            consequences.push("Potentially break existing integrations");
+        }
+        return this.confirmDestructiveOperation({
+            operation: "Function Deployment",
+            targets: functionNames,
+            consequences: consequences.length > 1 ? consequences : undefined,
+            requireExplicitConfirmation: options.isProduction || options.hasBreakingChanges,
+            confirmationText: options.isProduction ? "DEPLOY TO PRODUCTION" : "DEPLOY",
+        });
+    }
+    /**
+     * Shows operation summary and asks for final confirmation
+     */
+    static async showOperationSummary(title, summary, options = {}) {
+        MessageFormatter.section(`${title} Summary`);
+        Object.entries(summary).forEach(([key, value]) => {
+            const formattedKey = key.replace(/([A-Z])/g, ' $1').replace(/^./, str => str.toUpperCase());
+            if (Array.isArray(value)) {
+                MessageFormatter.info(`● ${formattedKey}:`, { skipLogging: true });
+                value.forEach(item => {
+                    MessageFormatter.debug(`  • ${item}`, undefined, { skipLogging: true });
+                });
+            }
+            else {
+                MessageFormatter.info(`● ${formattedKey}: ${String(value)}`, { skipLogging: true });
+            }
+        });
+        if (options.warningMessage) {
+            MessageFormatter.warning(`⚠️  ${options.warningMessage}`, { skipLogging: true });
+        }
+        if (options.confirmationRequired !== false) {
+            const { confirmed } = await inquirer.prompt([{
+                    type: 'confirm',
+                    name: 'confirmed',
+                    message: 'Continue with this operation?',
+                    default: true
+                }]);
+            return confirmed;
+        }
+        return true;
+    }
+    /**
+     * Interactive selection with confirmation
+     */
+    static async selectWithConfirmation(items, options) {
+        const choices = items.map((item, index) => ({
+            name: options.displayProperty ? String(item[options.displayProperty]) : String(item),
+            value: item,
+        }));
+        const prompt = options.multiSelect ? 'checkbox' : 'list';
+        const { selection } = await inquirer.prompt([{
+                type: prompt,
+                name: 'selection',
+                message: options.message,
+                choices,
+                validate: options.validator ? (input) => {
+                    const result = options.validator(Array.isArray(input) ? input : [input]);
+                    return result;
+                } : undefined,
+            }]);
+        const selectedItems = Array.isArray(selection) ? selection : [selection];
+        if (options.confirmMessage) {
+            const confirmMessage = options.confirmMessage.replace('{count}', selectedItems.length.toString());
+            const { confirmed } = await inquirer.prompt([{
+                    type: 'confirm',
+                    name: 'confirmed',
+                    message: confirmMessage,
+                    default: true
+                }]);
+            if (!confirmed) {
+                return [];
+            }
+        }
+        return selectedItems;
+    }
+    /**
+     * Confirms overwriting an existing file or directory
+     */
+    static async confirmOverwrite(target) {
+        const { confirmed } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'confirmed',
+                message: chalk.yellow(`${target} already exists. Overwrite?`),
+                default: false
+            }]);
+        return confirmed;
+    }
+    /**
+     * Confirms removal of a file
+     */
+    static async confirmRemoval(target) {
+        const { confirmed } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'confirmed',
+                message: chalk.red(target),
+                default: false
+            }]);
+        return confirmed;
+    }
+}