appwrite-utils-cli 1.11.0 → 1.12.0

package/dist/shared/operationsTable.js

@@ -0,0 +1,287 @@
+import { logger } from 'appwrite-utils-helpers';
+import { tryAwaitWithRetry } from "appwrite-utils-helpers";
+import { Query, ID } from "node-appwrite";
+import { OPERATIONS_TABLE_ID, OPERATIONS_TABLE_NAME, OperationRecordSchema, } from "./operationsTableSchema.js";
+/**
+ * Operations Table Manager
+ *
+ * Manages dynamic operations tracking tables in each database.
+ * Creates _appwrite_operations table on-demand for tracking imports, exports, transfers, etc.
+ */
+/**
+ * Checks if operations table exists in database
+ */
+async function tableExists(db, databaseId) {
+    try {
+        await db.getTable({ databaseId, tableId: OPERATIONS_TABLE_ID });
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Creates the operations tracking table in the specified database
+ * Table is created with underscore prefix to indicate it's a system table
+ */
+export async function createOperationsTable(db, databaseId) {
+    const exists = await tableExists(db, databaseId);
+    if (!exists) {
+        logger.info("Creating operations tracking table", {
+            databaseId,
+            tableId: OPERATIONS_TABLE_ID,
+        });
+        await tryAwaitWithRetry(async () => {
+            await db.createTable({
+                databaseId,
+                id: OPERATIONS_TABLE_ID,
+                name: OPERATIONS_TABLE_NAME,
+            });
+        });
+    }
+    // Always ensure attributes exist (handles partial creation from previous runs)
+    const attributes = [
+        {
+            key: "operationType",
+            type: "string",
+            size: 255,
+            required: true,
+        },
+        {
+            key: "targetTable",
+            type: "string",
+            size: 255,
+            required: false,
+        },
+        {
+            key: "status",
+            type: "enum",
+            elements: ["pending", "in_progress", "completed", "failed", "cancelled"],
+            required: false,
+            default: "pending",
+        },
+        {
+            key: "progress",
+            type: "integer",
+            required: false,
+            default: 0,
+        },
+        {
+            key: "total",
+            type: "integer",
+            required: false,
+            default: 0,
+        },
+        {
+            key: "data",
+            type: "string",
+            size: 1048576, // 1MB for serialized data
+            required: false,
+        },
+        {
+            key: "error",
+            type: "string",
+            size: 65535,
+            required: false,
+        },
+    ];
+    for (const attr of attributes) {
+        try {
+            await db.createAttribute({
+                databaseId,
+                tableId: OPERATIONS_TABLE_ID,
+                ...attr,
+            });
+        }
+        catch (error) {
+            // Attribute may already exist from a previous run — that's fine, skip it
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.includes("already exists") || msg.includes("column_already_exists")) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    logger.info("Operations tracking table ready", {
+        databaseId,
+        tableId: OPERATIONS_TABLE_ID,
+        attributes: attributes.length,
+    });
+}
+/**
+ * Finds an existing operation or creates a new one
+ * Useful for resuming interrupted operations
+ */
+export async function findOrCreateOperation(db, databaseId, operationType, params) {
+    // Ensure operations table exists
+    await createOperationsTable(db, databaseId);
+    // Try to find existing pending operation
+    try {
+        const queries = [
+            Query.equal("operationType", operationType),
+            Query.equal("status", "pending"),
+        ];
+        if (params?.targetTable) {
+            queries.push(Query.equal("targetTable", params.targetTable));
+        }
+        const response = await db.listRows({
+            databaseId,
+            tableId: OPERATIONS_TABLE_ID,
+            queries,
+        });
+        if (response.rows && response.rows.length > 0) {
+            logger.debug("Found existing operation", {
+                operationId: response.rows[0].$id,
+                operationType,
+            });
+            return response.rows[0];
+        }
+    }
+    catch (error) {
+        logger.debug("No existing operation found, creating new one", {
+            operationType,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Create new operation
+    const newOperation = {
+        operationType,
+        targetTable: params?.targetTable,
+        status: "pending",
+        progress: params?.progress ?? 0,
+        total: params?.total ?? 0,
+        data: params?.data ? JSON.stringify(params.data) : undefined,
+        error: params?.error,
+    };
+    const result = await db.createRow({
+        databaseId,
+        tableId: OPERATIONS_TABLE_ID,
+        id: ID.unique(),
+        data: newOperation,
+    });
+    logger.info("Created new operation", {
+        operationId: result.data?.$id,
+        operationType,
+    });
+    return result.data;
+}
+/**
+ * Updates an existing operation record
+ */
+export async function updateOperation(db, databaseId, operationId, updates) {
+    // Prepare update data (exclude system fields like $id, $createdAt, $updatedAt)
+    const updateData = {};
+    if (updates.operationType !== undefined)
+        updateData.operationType = updates.operationType;
+    if (updates.targetTable !== undefined)
+        updateData.targetTable = updates.targetTable;
+    if (updates.status !== undefined)
+        updateData.status = updates.status;
+    if (updates.progress !== undefined)
+        updateData.progress = updates.progress;
+    if (updates.total !== undefined)
+        updateData.total = updates.total;
+    if (updates.error !== undefined)
+        updateData.error = updates.error;
+    if (updates.data !== undefined) {
+        updateData.data =
+            typeof updates.data === "string"
+                ? updates.data
+                : JSON.stringify(updates.data);
+    }
+    try {
+        const result = await db.updateRow({
+            databaseId,
+            tableId: OPERATIONS_TABLE_ID,
+            id: operationId,
+            data: updateData,
+        });
+        logger.debug("Updated operation", {
+            operationId,
+            updates: Object.keys(updateData),
+        });
+        return result.data;
+    }
+    catch (error) {
+        logger.error("Failed to update operation", {
+            operationId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+/**
+ * Gets a single operation by ID
+ */
+export async function getOperation(db, databaseId, operationId) {
+    try {
+        const result = await db.getRow({
+            databaseId,
+            tableId: OPERATIONS_TABLE_ID,
+            id: operationId,
+        });
+        return result.data;
+    }
+    catch (error) {
+        logger.debug("Operation not found", {
+            operationId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Cleans up old completed operations
+ * @param olderThan - Optional date, defaults to operations older than 7 days
+ * @returns Number of operations deleted
+ */
+export async function cleanupOperations(db, databaseId, olderThan) {
+    const cutoffDate = olderThan || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000); // 7 days ago
+    const cutoffIso = cutoffDate.toISOString();
+    try {
+        // Query for completed operations older than cutoff
+        const response = await db.listRows({
+            databaseId,
+            tableId: OPERATIONS_TABLE_ID,
+            queries: [
+                Query.equal("status", ["completed", "failed", "cancelled"]),
+                Query.lessThan("$createdAt", cutoffIso),
+            ],
+        });
+        if (!response.rows || response.rows.length === 0) {
+            logger.debug("No old operations to clean up", { databaseId });
+            return 0;
+        }
+        // Delete in batches
+        let deletedCount = 0;
+        for (const operation of response.rows) {
+            try {
+                await db.deleteRow({
+                    databaseId,
+                    tableId: OPERATIONS_TABLE_ID,
+                    id: operation.$id,
+                });
+                deletedCount++;
+            }
+            catch (error) {
+                logger.warn("Failed to delete operation", {
+                    operationId: operation.$id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        logger.info("Cleaned up old operations", {
+            databaseId,
+            deletedCount,
+            cutoffDate: cutoffIso,
+        });
+        return deletedCount;
+    }
+    catch (error) {
+        logger.error("Failed to cleanup operations", {
+            databaseId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return 0;
+    }
+}

package/dist/shared/operationsTableSchema.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Schema for operation tracking table (_appwrite_operations)
+ *
+ * This table is created dynamically in each database to track long-running operations
+ * like imports, exports, transfers, and backups.
+ */
+import { z } from "zod";
+export interface OperationRecord {
+    $id: string;
+    $createdAt: string;
+    $updatedAt: string;
+    operationType: string;
+    targetTable?: string;
+    status: OperationStatus;
+    progress: number;
+    total: number;
+    data?: any;
+    error?: string;
+}
+export type OperationStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+export declare const OPERATION_STATUSES: readonly ["pending", "in_progress", "completed", "failed", "cancelled"];
+export declare const OperationStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    completed: "completed";
+    cancelled: "cancelled";
+    failed: "failed";
+}>;
+export declare const OperationRecordSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $createdAt: z.ZodString;
+    $updatedAt: z.ZodString;
+    operationType: z.ZodString;
+    targetTable: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+        cancelled: "cancelled";
+        failed: "failed";
+    }>;
+    progress: z.ZodNumber;
+    total: z.ZodNumber;
+    data: z.ZodOptional<z.ZodAny>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const OPERATIONS_TABLE_ID = "appwrite_operations";
+export declare const OPERATIONS_TABLE_NAME = "Operations Tracking";

package/dist/shared/operationsTableSchema.js

@@ -0,0 +1,35 @@
+/**
+ * Schema for operation tracking table (_appwrite_operations)
+ *
+ * This table is created dynamically in each database to track long-running operations
+ * like imports, exports, transfers, and backups.
+ */
+import { z } from "zod";
+export const OPERATION_STATUSES = [
+    'pending',
+    'in_progress',
+    'completed',
+    'failed',
+    'cancelled'
+];
+export const OperationStatusSchema = z.enum([
+    'pending',
+    'in_progress',
+    'completed',
+    'failed',
+    'cancelled'
+]);
+export const OperationRecordSchema = z.object({
+    $id: z.string(),
+    $createdAt: z.string(),
+    $updatedAt: z.string(),
+    operationType: z.string(),
+    targetTable: z.string().optional(),
+    status: OperationStatusSchema,
+    progress: z.number(),
+    total: z.number(),
+    data: z.any().optional(),
+    error: z.string().optional()
+});
+export const OPERATIONS_TABLE_ID = "appwrite_operations";
+export const OPERATIONS_TABLE_NAME = "Operations Tracking";

package/dist/shared/progressManager.d.ts

@@ -0,0 +1,62 @@
+export interface ProgressOptions {
+    title?: string;
+    showETA?: boolean;
+    showSpeed?: boolean;
+    showPercentage?: boolean;
+    width?: number;
+    format?: string;
+}
+export declare class ProgressManager {
+    private static instances;
+    private bar;
+    private startTime;
+    private totalItems;
+    private completed;
+    private id;
+    private title;
+    private constructor();
+    static create(id: string, total: number, options?: ProgressOptions): ProgressManager;
+    static get(id: string): ProgressManager | undefined;
+    update(current: number, detail?: string): void;
+    increment(amount?: number, detail?: string): void;
+    setTotal(total: number): void;
+    stop(showSummary?: boolean): void;
+    fail(error: string): void;
+    getStats(): {
+        completed: number;
+        total: number;
+        percentage: number;
+        duration: number;
+        rate: number;
+        remaining: number;
+        eta: number;
+    };
+    static stopAll(): void;
+}
+export declare class MultiProgressManager {
+    private multiBar;
+    private bars;
+    private startTime;
+    constructor(options?: ProgressOptions);
+    addTask(id: string, total: number, title: string): void;
+    updateTask(id: string, current: number, detail?: string): void;
+    incrementTask(id: string, amount?: number, detail?: string): void;
+    completeTask(id: string): void;
+    failTask(id: string, error: string): void;
+    stop(showSummary?: boolean): void;
+    getTaskStats(id: string): {
+        completed: number;
+        total: number;
+        percentage: number;
+        remaining: number;
+    } | null;
+    getAllStats(): Map<string, any>;
+}
+export declare const ProgressUtils: {
+    withProgress<T>(id: string, total: number, title: string, operation: (progress: ProgressManager) => Promise<T>): Promise<T>;
+    processArrayWithProgress<T, R>(items: T[], processor: (item: T, index: number) => Promise<R>, options?: {
+        title?: string;
+        batchSize?: number;
+        showDetail?: boolean;
+    }): Promise<R[]>;
+};

package/dist/shared/progressManager.js

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

package/dist/shared/relationshipExtractor.d.ts

@@ -0,0 +1,56 @@
+import type { AppwriteConfig, Attribute, RelationshipAttribute } from "appwrite-utils";
+/**
+ * Represents detailed information about a two-way relationship between collections
+ */
+export interface RelationshipDetail {
+    parentCollection: string;
+    childCollection: string;
+    parentKey: string;
+    childKey: string;
+    isArray: boolean;
+    isChild: boolean;
+}
+/**
+ * Represents basic relationship information for JSON schema generation
+ */
+export interface SimpleRelationship {
+    attributeKey: string;
+    relatedCollection: string;
+    relationType: string;
+    isArray: boolean;
+}
+/**
+ * Helper function to resolve collection name from ID or name
+ * @param config - Appwrite configuration containing collections
+ * @param idOrName - Collection ID or name to resolve
+ * @returns Resolved collection name, or the original input if not found
+ */
+export declare function resolveCollectionName(config: AppwriteConfig, idOrName: string): string;
+/**
+ * Determines if a relationship type results in an array
+ * @param relationType - The type of relationship (oneToOne, oneToMany, manyToOne, manyToMany)
+ * @returns true if the relationship results in an array
+ */
+export declare function isArrayRelationship(relationType: string): boolean;
+/**
+ * Extracts two-way relationship details from collections for Zod schema generation
+ * This handles complex bidirectional relationships with parent-child tracking
+ *
+ * @param config - Appwrite configuration containing collections
+ * @returns Map of collection names to their relationship details
+ */
+export declare function extractTwoWayRelationships(config: AppwriteConfig): Map<string, RelationshipDetail[]>;
+/**
+ * Extracts simple relationship information from collections for JSON schema generation
+ * This handles one-way and basic relationship tracking
+ *
+ * @param config - Appwrite configuration containing collections
+ * @returns Map of collection names to their simple relationships
+ */
+export declare function extractSimpleRelationships(config: AppwriteConfig): Map<string, SimpleRelationship[]>;
+/**
+ * Extracts all relationship attributes from a collection's attributes
+ * @param attributes - Array of collection attributes
+ * @returns Array of relationship attributes only
+ */
+export declare function filterRelationshipAttributes(attributes: Attribute[]): RelationshipAttribute[];