appwrite-utils-cli 1.9.5 → 1.9.7

package/dist/collections/tableOperations.js

@@ -90,11 +90,13 @@ export function normalizeAttributeToComparable(attr) {
     return base;
 }
 export function normalizeColumnToComparable(col) {
-    // Detect enum surfaced as string+elements from server and normalize to enum for comparison
+    // Detect enum surfaced as string+elements or string+format:enum from server and normalize to enum for comparison
     let t = String((col?.type ?? col?.columnType ?? '')).toLowerCase();
     const hasElements = Array.isArray(col?.elements) && col.elements.length > 0;
-    if (t === 'string' && hasElements)
+    const hasEnumFormat = (col?.format === 'enum');
+    if (t === 'string' && (hasElements || hasEnumFormat)) {
         t = 'enum';
+    }
     const base = {
         key: col?.key,
         type: t,
@@ -185,18 +187,27 @@ export function isIndexEqualToIndex(a, b) {
     if (String(a.type).toLowerCase() !== String(b.type).toLowerCase())
         return false;
     // Compare attributes as sets (order-insensitive)
-    const attrsA = Array.isArray(a.attributes) ? [...a.attributes].sort() : [];
-    const attrsB = Array.isArray(b.attributes) ? [...b.attributes].sort() : [];
+    // Support TablesDB which returns 'columns' instead of 'attributes'
+    const attrsAraw = Array.isArray(a.attributes)
+        ? a.attributes
+        : (Array.isArray(a.columns) ? a.columns : []);
+    const attrsA = [...attrsAraw].sort();
+    const attrsB = Array.isArray(b.attributes)
+        ? [...b.attributes].sort()
+        : (Array.isArray(b.columns) ? [...b.columns].sort() : []);
     if (attrsA.length !== attrsB.length)
         return false;
     for (let i = 0; i < attrsA.length; i++)
         if (attrsA[i] !== attrsB[i])
             return false;
-    // Orders are only considered if BOTH have orders defined
-    const hasOrdersA = Array.isArray(a.orders) && a.orders.length > 0;
-    const hasOrdersB = Array.isArray(b.orders) && b.orders.length > 0;
-    if (hasOrdersA && hasOrdersB) {
-        const ordersA = [...a.orders].sort();
+    // Orders are only considered if CONFIG (b) has orders defined
+    // This prevents false positives when Appwrite returns orders but user didn't specify them
+    const hasConfigOrders = Array.isArray(b.orders) && b.orders.length > 0;
+    if (hasConfigOrders) {
+        // Some APIs may expose 'directions' instead of 'orders'
+        const ordersA = Array.isArray(a.orders)
+            ? [...a.orders].sort()
+            : (Array.isArray(a.directions) ? [...a.directions].sort() : []);
         const ordersB = [...b.orders].sort();
         if (ordersA.length !== ordersB.length)
             return false;
@@ -204,7 +215,6 @@ export function isIndexEqualToIndex(a, b) {
             if (ordersA[i] !== ordersB[i])
                 return false;
     }
-    // If only one side has orders, treat as equal (orders unspecified by user)
     return true;
 }
 /**
@@ -213,6 +223,7 @@ export function isIndexEqualToIndex(a, b) {
 function compareColumnProperties(oldColumn, newAttribute, columnType) {
     const changes = [];
     const t = String(columnType || newAttribute.type || '').toLowerCase();
+    const key = newAttribute?.key || 'unknown';
     const mutableProps = MUTABLE_PROPERTIES[t] || [];
     const immutableProps = IMMUTABLE_PROPERTIES[t] || [];
     const getNewVal = (prop) => {
@@ -233,8 +244,9 @@ function compareColumnProperties(oldColumn, newAttribute, columnType) {
         let newValue = getNewVal(prop);
         // Special-case: enum elements empty/missing should not trigger updates
         if (t === 'enum' && prop === 'elements') {
-            if (!Array.isArray(newValue) || newValue.length === 0)
+            if (!Array.isArray(newValue) || newValue.length === 0) {
                 newValue = oldValue;
+            }
         }
         if (Array.isArray(oldValue) && Array.isArray(newValue)) {
             if (oldValue.length !== newValue.length || oldValue.some((v, i) => v !== newValue[i])) {
@@ -260,7 +272,8 @@ function compareColumnProperties(oldColumn, newAttribute, columnType) {
     // Type change requires recreate (normalize string+elements to enum on old side)
     const oldTypeRaw = String(oldColumn?.type || oldColumn?.columnType || '').toLowerCase();
     const oldHasElements = Array.isArray(oldColumn?.elements) && oldColumn.elements.length > 0;
-    const oldType = oldTypeRaw === 'string' && oldHasElements ? 'enum' : oldTypeRaw;
+    const oldHasEnumFormat = (oldColumn?.format === 'enum');
+    const oldType = oldTypeRaw === 'string' && (oldHasElements || oldHasEnumFormat) ? 'enum' : oldTypeRaw;
     if (oldType && t && oldType !== t && TYPE_CHANGE_REQUIRES_RECREATE.includes(oldType)) {
         changes.push({ property: 'type', oldValue: oldType, newValue: t, requiresRecreate: true });
     }

package/dist/config/ConfigManager.js

@@ -3,6 +3,7 @@ import path from "path";
 import { ConfigDiscoveryService, ConfigLoaderService, ConfigMergeService, ConfigValidationService, SessionAuthService, } from "./services/index.js";
 import { MessageFormatter } from "../shared/messageFormatter.js";
 import { logger } from "../shared/logging.js";
+import { detectAppwriteVersionCached } from "../utils/versionDetection.js";
 /**
  * Centralized configuration manager with intelligent caching and session management.
  *
@@ -178,6 +179,30 @@ export class ConfigManager {
                     `Run with reportValidation: true to see details.`);
             }
         }
+        // 8. Run version detection and set apiMode if not explicitly configured
+        if (!config.apiMode || config.apiMode === 'auto') {
+            try {
+                logger.debug('Running version detection for API mode detection', {
+                    prefix: "ConfigManager",
+                    endpoint: config.appwriteEndpoint
+                });
+                const versionResult = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey);
+                config.apiMode = versionResult.apiMode;
+                logger.info(`API mode detected: ${config.apiMode}`, {
+                    prefix: "ConfigManager",
+                    method: versionResult.detectionMethod,
+                    confidence: versionResult.confidence,
+                    serverVersion: versionResult.serverVersion,
+                });
+            }
+            catch (error) {
+                logger.warn('Version detection failed, defaulting to legacy mode', {
+                    prefix: "ConfigManager",
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+                config.apiMode = 'legacy';
+            }
+        }
         // 8. Cache the config
         this.cachedConfig = config;
         this.cachedConfigPath = configPath;

package/dist/shared/attributeMapper.js

@@ -140,7 +140,7 @@ export function mapToCreateAttributeParams(attr, base) {
  * so we never send an empty elements array (preserve existing on server).
  */
 export function mapToUpdateAttributeParams(attr, base) {
-    const type = String(attr.type || "").toLowerCase();
+    const type = String((attr.type == 'string' && attr.format !== 'enum') || attr.type !== 'string' ? attr.type : 'enum').toLowerCase();
     const params = {
         databaseId: base.databaseId,
         tableId: base.tableId,

package/dist/tables/indexManager.d.ts

@@ -0,0 +1,65 @@
+import type { Index } from "appwrite-utils";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import type { Models } from "node-appwrite";
+export interface IndexOperation {
+    type: 'create' | 'update' | 'skip' | 'delete';
+    index: Index;
+    existingIndex?: Models.Index;
+    reason?: string;
+}
+export interface IndexOperationPlan {
+    toCreate: IndexOperation[];
+    toUpdate: IndexOperation[];
+    toSkip: IndexOperation[];
+    toDelete: IndexOperation[];
+}
+export interface IndexExecutionResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    deleted: string[];
+    errors: Array<{
+        key: string;
+        error: string;
+    }>;
+    summary: {
+        total: number;
+        created: number;
+        updated: number;
+        skipped: number;
+        deleted: number;
+        errors: number;
+    };
+}
+/**
+ * Plan index operations by comparing desired indexes with existing ones
+ * Uses the existing isIndexEqualToIndex function for consistent comparison
+ */
+export declare function planIndexOperations(desiredIndexes: Index[], existingIndexes: Models.Index[]): IndexOperationPlan;
+/**
+ * Plan index deletions for indexes that exist but aren't in the desired configuration
+ */
+export declare function planIndexDeletions(desiredIndexKeys: Set<string>, existingIndexes: Models.Index[]): IndexOperation[];
+/**
+ * Execute index operations with proper error handling and status monitoring
+ */
+export declare function executeIndexOperations(adapter: DatabaseAdapter, databaseId: string, tableId: string, plan: IndexOperationPlan): Promise<IndexExecutionResult>;
+/**
+ * Execute index deletions with proper error handling
+ */
+export declare function executeIndexDeletions(adapter: DatabaseAdapter, databaseId: string, tableId: string, deletions: IndexOperation[]): Promise<{
+    deleted: string[];
+    errors: Array<{
+        key: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Main function to create/update indexes via adapter
+ * This replaces the messy inline code in methods.ts
+ */
+export declare function createOrUpdateIndexesViaAdapter(adapter: DatabaseAdapter, databaseId: string, tableId: string, desiredIndexes: Index[], configIndexes?: Index[]): Promise<void>;
+/**
+ * Handle index deletions for obsolete indexes
+ */
+export declare function deleteObsoleteIndexesViaAdapter(adapter: DatabaseAdapter, databaseId: string, tableId: string, desiredIndexKeys: Set<string>): Promise<void>;

package/dist/tables/indexManager.js

@@ -0,0 +1,294 @@
+import { isIndexEqualToIndex } from "../collections/tableOperations.js";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+import { delay, tryAwaitWithRetry } from "../utils/helperFunctions.js";
+/**
+ * Plan index operations by comparing desired indexes with existing ones
+ * Uses the existing isIndexEqualToIndex function for consistent comparison
+ */
+export function planIndexOperations(desiredIndexes, existingIndexes) {
+    const plan = {
+        toCreate: [],
+        toUpdate: [],
+        toSkip: [],
+        toDelete: []
+    };
+    for (const desiredIndex of desiredIndexes) {
+        const existingIndex = existingIndexes.find(idx => idx.key === desiredIndex.key);
+        if (!existingIndex) {
+            // Index doesn't exist - create it
+            plan.toCreate.push({
+                type: 'create',
+                index: desiredIndex,
+                reason: 'New index'
+            });
+        }
+        else if (isIndexEqualToIndex(existingIndex, desiredIndex)) {
+            // Index exists and is identical - skip it
+            plan.toSkip.push({
+                type: 'skip',
+                index: desiredIndex,
+                existingIndex,
+                reason: 'Index unchanged'
+            });
+        }
+        else {
+            // Index exists but is different - update it
+            plan.toUpdate.push({
+                type: 'update',
+                index: desiredIndex,
+                existingIndex,
+                reason: 'Index configuration changed'
+            });
+        }
+    }
+    return plan;
+}
+/**
+ * Plan index deletions for indexes that exist but aren't in the desired configuration
+ */
+export function planIndexDeletions(desiredIndexKeys, existingIndexes) {
+    const deletions = [];
+    for (const existingIndex of existingIndexes) {
+        if (!desiredIndexKeys.has(existingIndex.key)) {
+            deletions.push({
+                type: 'delete',
+                index: existingIndex, // Convert Models.Index to Index for compatibility
+                reason: 'Obsolete index'
+            });
+        }
+    }
+    return deletions;
+}
+/**
+ * Execute index operations with proper error handling and status monitoring
+ */
+export async function executeIndexOperations(adapter, databaseId, tableId, plan) {
+    const result = {
+        created: [],
+        updated: [],
+        skipped: [],
+        deleted: [],
+        errors: [],
+        summary: {
+            total: 0,
+            created: 0,
+            updated: 0,
+            skipped: 0,
+            deleted: 0,
+            errors: 0
+        }
+    };
+    // Execute creates
+    for (const operation of plan.toCreate) {
+        try {
+            await adapter.createIndex({
+                databaseId,
+                tableId,
+                key: operation.index.key,
+                type: operation.index.type,
+                attributes: operation.index.attributes,
+                orders: operation.index.orders || []
+            });
+            result.created.push(operation.index.key);
+            MessageFormatter.success(`Created index ${operation.index.key}`, { prefix: 'Indexes' });
+            // Wait for index to become available
+            await waitForIndexAvailable(adapter, databaseId, tableId, operation.index.key);
+            await delay(150); // Brief delay between operations
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push({ key: operation.index.key, error: errorMessage });
+            MessageFormatter.error(`Failed to create index ${operation.index.key}`, error instanceof Error ? error : new Error(String(error)), { prefix: 'Indexes' });
+        }
+    }
+    // Execute updates (delete + recreate)
+    for (const operation of plan.toUpdate) {
+        try {
+            // Delete existing index first
+            await adapter.deleteIndex({
+                databaseId,
+                tableId,
+                key: operation.index.key
+            });
+            await delay(100); // Brief delay for deletion to settle
+            // Create new index
+            await adapter.createIndex({
+                databaseId,
+                tableId,
+                key: operation.index.key,
+                type: operation.index.type,
+                attributes: operation.index.attributes,
+                orders: operation.index.orders || operation.existingIndex?.orders || []
+            });
+            result.updated.push(operation.index.key);
+            MessageFormatter.success(`Updated index ${operation.index.key}`, { prefix: 'Indexes' });
+            // Wait for index to become available
+            await waitForIndexAvailable(adapter, databaseId, tableId, operation.index.key);
+            await delay(150); // Brief delay between operations
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push({ key: operation.index.key, error: errorMessage });
+            MessageFormatter.error(`Failed to update index ${operation.index.key}`, error instanceof Error ? error : new Error(String(error)), { prefix: 'Indexes' });
+        }
+    }
+    // Execute skips
+    for (const operation of plan.toSkip) {
+        result.skipped.push(operation.index.key);
+        MessageFormatter.info(`Index ${operation.index.key} unchanged`, { prefix: 'Indexes' });
+    }
+    // Calculate summary
+    result.summary.total = result.created.length + result.updated.length + result.skipped.length + result.deleted.length;
+    result.summary.created = result.created.length;
+    result.summary.updated = result.updated.length;
+    result.summary.skipped = result.skipped.length;
+    result.summary.deleted = result.deleted.length;
+    result.summary.errors = result.errors.length;
+    return result;
+}
+/**
+ * Execute index deletions with proper error handling
+ */
+export async function executeIndexDeletions(adapter, databaseId, tableId, deletions) {
+    const result = {
+        deleted: [],
+        errors: []
+    };
+    for (const operation of deletions) {
+        try {
+            await adapter.deleteIndex({
+                databaseId,
+                tableId,
+                key: operation.index.key
+            });
+            result.deleted.push(operation.index.key);
+            MessageFormatter.info(`Deleted obsolete index ${operation.index.key}`, { prefix: 'Indexes' });
+            // Wait briefly for deletion to settle
+            await delay(500);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push({ key: operation.index.key, error: errorMessage });
+            MessageFormatter.error(`Failed to delete index ${operation.index.key}`, error instanceof Error ? error : new Error(String(error)), { prefix: 'Indexes' });
+        }
+    }
+    return result;
+}
+/**
+ * Wait for an index to become available with timeout and retry logic
+ * This is an adapter-aware version of the logic from collections/indexes.ts
+ */
+async function waitForIndexAvailable(adapter, databaseId, tableId, indexKey, maxWaitTime = 60000, // 1 minute
+checkInterval = 2000 // 2 seconds
+) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWaitTime) {
+        try {
+            const indexList = await adapter.listIndexes({ databaseId, tableId });
+            const indexes = indexList.data || indexList.indexes || [];
+            const index = indexes.find((idx) => idx.key === indexKey);
+            if (!index) {
+                MessageFormatter.error(`Index '${indexKey}' not found after creation`, undefined, { prefix: 'Indexes' });
+                return false;
+            }
+            switch (index.status) {
+                case 'available':
+                    return true;
+                case 'failed':
+                    MessageFormatter.error(`Index '${indexKey}' failed: ${index.error || 'unknown error'}`, undefined, { prefix: 'Indexes' });
+                    return false;
+                case 'stuck':
+                    MessageFormatter.warning(`Index '${indexKey}' is stuck`, { prefix: 'Indexes' });
+                    return false;
+                case 'processing':
+                case 'deleting':
+                    // Continue waiting
+                    break;
+                default:
+                    MessageFormatter.warning(`Unknown status '${index.status}' for index '${indexKey}'`, { prefix: 'Indexes' });
+                    break;
+            }
+        }
+        catch (error) {
+            MessageFormatter.error(`Error checking index '${indexKey}' status: ${error}`, undefined, { prefix: 'Indexes' });
+        }
+        await delay(checkInterval);
+    }
+    MessageFormatter.warning(`Timeout waiting for index '${indexKey}' to become available (${maxWaitTime}ms)`, { prefix: 'Indexes' });
+    return false;
+}
+/**
+ * Main function to create/update indexes via adapter
+ * This replaces the messy inline code in methods.ts
+ */
+export async function createOrUpdateIndexesViaAdapter(adapter, databaseId, tableId, desiredIndexes, configIndexes) {
+    if (!desiredIndexes || desiredIndexes.length === 0) {
+        MessageFormatter.info('No indexes to process', { prefix: 'Indexes' });
+        return;
+    }
+    MessageFormatter.info(`Processing ${desiredIndexes.length} indexes for table ${tableId}`, { prefix: 'Indexes' });
+    try {
+        // Get existing indexes
+        const existingIdxRes = await adapter.listIndexes({ databaseId, tableId });
+        const existingIndexes = existingIdxRes.data || existingIdxRes.indexes || [];
+        // Plan operations
+        const plan = planIndexOperations(desiredIndexes, existingIndexes);
+        // Show plan with icons (consistent with attribute handling)
+        const planParts = [];
+        if (plan.toCreate.length)
+            planParts.push(`➕  ${plan.toCreate.length} (${plan.toCreate.map(op => op.index.key).join(', ')})`);
+        if (plan.toUpdate.length)
+            planParts.push(`🔧  ${plan.toUpdate.length} (${plan.toUpdate.map(op => op.index.key).join(', ')})`);
+        if (plan.toSkip.length)
+            planParts.push(`⏭️  ${plan.toSkip.length}`);
+        MessageFormatter.info(`Plan → ${planParts.join('  |  ') || 'no changes'}`, { prefix: 'Indexes' });
+        // Execute operations
+        const result = await executeIndexOperations(adapter, databaseId, tableId, plan);
+        // Show summary
+        MessageFormatter.info(`Summary → ➕  ${result.summary.created}  |  🔧  ${result.summary.updated}  |  ⏭️  ${result.summary.skipped}`, { prefix: 'Indexes' });
+        // Handle errors if any
+        if (result.errors.length > 0) {
+            MessageFormatter.error(`${result.errors.length} index operations failed:`, undefined, { prefix: 'Indexes' });
+            for (const error of result.errors) {
+                MessageFormatter.error(`  ${error.key}: ${error.error}`, undefined, { prefix: 'Indexes' });
+            }
+        }
+    }
+    catch (error) {
+        MessageFormatter.error('Failed to process indexes', error instanceof Error ? error : new Error(String(error)), { prefix: 'Indexes' });
+        throw error;
+    }
+}
+/**
+ * Handle index deletions for obsolete indexes
+ */
+export async function deleteObsoleteIndexesViaAdapter(adapter, databaseId, tableId, desiredIndexKeys) {
+    try {
+        // Get existing indexes
+        const existingIdxRes = await adapter.listIndexes({ databaseId, tableId });
+        const existingIndexes = existingIdxRes.data || existingIdxRes.indexes || [];
+        // Plan deletions
+        const deletions = planIndexDeletions(desiredIndexKeys, existingIndexes);
+        if (deletions.length === 0) {
+            MessageFormatter.info('Plan → 🗑️  0 indexes', { prefix: 'Indexes' });
+            return;
+        }
+        // Show deletion plan
+        MessageFormatter.info(`Plan → 🗑️  ${deletions.length} (${deletions.map(op => op.index.key).join(', ')})`, { prefix: 'Indexes' });
+        // Execute deletions
+        const result = await executeIndexDeletions(adapter, databaseId, tableId, deletions);
+        // Show results
+        if (result.deleted.length > 0) {
+            MessageFormatter.success(`Deleted ${result.deleted.length} indexes: ${result.deleted.join(', ')}`, { prefix: 'Indexes' });
+        }
+        if (result.errors.length > 0) {
+            MessageFormatter.error(`${result.errors.length} index deletions failed:`, undefined, { prefix: 'Indexes' });
+            for (const error of result.errors) {
+                MessageFormatter.error(`  ${error.key}: ${error.error}`, undefined, { prefix: 'Indexes' });
+            }
+        }
+    }
+    catch (error) {
+        MessageFormatter.warning(`Could not evaluate index deletions: ${error?.message || error}`, { prefix: 'Indexes' });
+    }
+}

package/dist/utilsController.js

@@ -30,6 +30,7 @@ import { createImportSchemas } from "./migrations/yaml/generateImportSchemas.js"
 import { validateCollectionsTablesConfig, reportValidationResults, validateWithStrictMode } from "./config/configValidation.js";
 import { ConfigManager } from "./config/ConfigManager.js";
 import { ClientFactory } from "./utils/ClientFactory.js";
+import { clearProcessingState, processQueue } from "./shared/operationQueue.js";
 export class UtilsController {
     // ──────────────────────────────────────────────────
     // SINGLETON PATTERN
@@ -458,7 +459,6 @@ export class UtilsController {
         // Ensure we don't carry state between databases in a multi-db push
         // This resets processed sets and name->id mapping per database
         try {
-            const { clearProcessingState } = await import('./shared/operationQueue.js');
             clearProcessingState();
         }
         catch { }
@@ -475,6 +475,15 @@ export class UtilsController {
             logger.debug("Adapter unavailable, falling back to legacy Databases path", { prefix: "UtilsController" });
             await createOrUpdateCollections(this.database, database.$id, this.config, deletedCollections, collections);
         }
+        // Safety net: Process any remaining queued operations to complete relationship sync
+        try {
+            MessageFormatter.info(`🔄 Processing final operation queue for database ${database.$id}`, { prefix: "UtilsController" });
+            await processQueue(this.adapter || this.database, database.$id);
+            MessageFormatter.info(`✅ Operation queue processing completed`, { prefix: "UtilsController" });
+        }
+        catch (error) {
+            MessageFormatter.error(`Failed to process operation queue`, error instanceof Error ? error : new Error(String(error)), { prefix: 'UtilsController' });
+        }
     }
     async generateSchemas() {
         // Schema generation doesn't need Appwrite connection, just config

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.9.5",
+  "version": "1.9.7",
   "main": "src/main.ts",
   "type": "module",
   "repository": {