appwrite-utils-cli 1.6.5 → 1.6.7

package/dist/collections/indexes.js

@@ -3,6 +3,8 @@ import { Databases, IndexType, Query } from "node-appwrite";
 import { delay, tryAwaitWithRetry, calculateExponentialBackoff } from "../utils/helperFunctions.js";
 import { isLegacyDatabases } from "../utils/typeGuards.js";
 import { MessageFormatter } from "../shared/messageFormatter.js";
+// System attributes that are always available for indexing in Appwrite
+const SYSTEM_ATTRIBUTES = ['$id', '$createdAt', '$updatedAt', '$permissions'];
 /**
  * Wait for index to become available, with retry logic for stuck indexes and exponential backoff
  */
@@ -72,10 +74,12 @@ export const createOrUpdateIndexWithStatusCheck = async (dbId, db, collectionId,
         // First, validate that all required attributes exist
         const freshCollection = await db.getCollection(dbId, collectionId);
         const existingAttributeKeys = freshCollection.attributes.map((attr) => attr.key);
-        const missingAttributes = index.attributes.filter(attr => !existingAttributeKeys.includes(attr));
+        // Include system attributes that are always available
+        const allAvailableAttributes = [...existingAttributeKeys, ...SYSTEM_ATTRIBUTES];
+        const missingAttributes = index.attributes.filter(attr => !allAvailableAttributes.includes(attr));
         if (missingAttributes.length > 0) {
             MessageFormatter.error(`Index '${index.key}' cannot be created: missing attributes [${missingAttributes.join(', ')}] (type: ${index.type})`);
-            MessageFormatter.error(`Available attributes: [${existingAttributeKeys.join(', ')}]`);
+            MessageFormatter.error(`Available attributes: [${existingAttributeKeys.join(', ')}, ${SYSTEM_ATTRIBUTES.join(', ')}]`);
             return false; // Don't retry if attributes are missing
         }
         // Try to create/update the index using existing logic
@@ -169,12 +173,30 @@ export const createOrUpdateIndex = async (dbId, db, collectionId, index) => {
         // No existing index, create it
         createIndex = true;
     }
-    else if (!existingIndex.indexes.some((existingIndex) => (existingIndex.key === index.key &&
-        existingIndex.type === index.type &&
-        existingIndex.attributes === index.attributes))) {
-        // Existing index doesn't match, delete and recreate
-        await db.deleteIndex(dbId, collectionId, existingIndex.indexes[0].key);
-        createIndex = true;
+    else {
+        const existing = existingIndex.indexes[0];
+        // Check key and type
+        const keyMatches = existing.key === index.key;
+        const typeMatches = existing.type === index.type;
+        // Compare attributes as SETS (order doesn't matter, only content)
+        const existingAttrsSet = new Set(existing.attributes);
+        const newAttrsSet = new Set(index.attributes);
+        const attributesMatch = existingAttrsSet.size === newAttrsSet.size &&
+            [...existingAttrsSet].every(attr => newAttrsSet.has(attr));
+        // Compare orders as SETS if both exist (order doesn't matter)
+        let ordersMatch = true;
+        if (index.orders && existing.orders) {
+            const existingOrdersSet = new Set(existing.orders);
+            const newOrdersSet = new Set(index.orders);
+            ordersMatch =
+                existingOrdersSet.size === newOrdersSet.size &&
+                    [...existingOrdersSet].every(ord => newOrdersSet.has(ord));
+        }
+        // Only recreate if something genuinely changed
+        if (!keyMatches || !typeMatches || !attributesMatch || !ordersMatch) {
+            await db.deleteIndex(dbId, collectionId, existing.key);
+            createIndex = true;
+        }
     }
     if (createIndex) {
         // Ensure orders array exists and matches attributes length

package/dist/collections/methods.js

@@ -224,10 +224,14 @@ export const createOrUpdateCollections = async (database, databaseId, config, de
         attributes);
         // Add delay after creating attributes
         await delay(250);
-        // For PUSH operations, only use indexes from local config (not remote)
-        const indexesToUse = indexes || [];
+        // Prefer local config indexes, but fall back to collection's own indexes if no local config exists
+        const localCollectionConfig = config.collections?.find(c => c.name === collectionData.name || c.$id === collectionData.$id);
+        const indexesToUse = localCollectionConfig?.indexes ?? indexes ?? [];
         MessageFormatter.progress("Creating Indexes", { prefix: "Collections" });
         await createOrUpdateIndexesWithStatusCheck(databaseId, database, collectionToUse.$id, collectionToUse, indexesToUse);
+        // Delete indexes that exist on server but not in local config
+        const { deleteObsoleteIndexes } = await import('../shared/indexManager.js');
+        await deleteObsoleteIndexes(database, databaseId, collectionToUse, { indexes: indexesToUse }, { verbose: true });
         // Mark this collection as fully processed to prevent re-processing
         markCollectionProcessed(collectionToUse.$id, collectionData.name);
         // Add delay after creating indexes
@@ -424,8 +428,9 @@ export const createOrUpdateCollectionsViaAdapter = async (adapter, databaseId, c
                 }
             }
         }
-        // Indexes
-        const idxs = (indexes || []);
+        // Prefer local config indexes, but fall back to collection's own indexes if no local config exists (TablesDB path)
+        const localTableConfig = config.collections?.find(c => c.name === collectionData.name || c.$id === collectionData.$id);
+        const idxs = (localTableConfig?.indexes ?? indexes ?? []);
         for (const idx of idxs) {
             try {
                 await adapter.createIndex({

package/dist/config/services/ConfigLoaderService.d.ts

@@ -90,6 +90,23 @@ export declare class ConfigLoaderService {
             source2: string;
         }>;
     }>;
+    /**
+     * Loads tables first (higher priority), then collections (backward compatibility)
+     * Used for TablesDB projects (>= 1.8.0)
+     * @param tablesDir Path to the tables directory
+     * @param collectionsDir Path to the collections directory
+     * @returns Loading result with items, counts, and conflicts
+     */
+    loadTablesFirst(tablesDir: string, collectionsDir: string): Promise<{
+        items: Collection[];
+        fromCollections: number;
+        fromTables: number;
+        conflicts: Array<{
+            name: string;
+            source1: string;
+            source2: string;
+        }>;
+    }>;
     /**
      * Validates that a configuration file can be loaded
      * @param configPath Path to the configuration file

package/dist/config/services/ConfigLoaderService.js

@@ -112,6 +112,42 @@ export class ConfigLoaderService {
                     };
                 }
             }
+            // Load collections and tables from their respective directories
+            const configDir = path.dirname(yamlPath);
+            const collectionsDir = path.join(configDir, config.schemaConfig?.collectionsDirectory || "collections");
+            const tablesDir = path.join(configDir, config.schemaConfig?.tablesDirectory || "tables");
+            // Detect API mode to determine priority order
+            let apiMode = 'legacy';
+            try {
+                const { detectAppwriteVersionCached } = await import('../../utils/versionDetection.js');
+                const detection = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey);
+                apiMode = detection.apiMode;
+            }
+            catch {
+                // Fallback to legacy if detection fails
+            }
+            // Load with correct priority based on API mode
+            const { items, conflicts, fromCollections, fromTables } = apiMode === 'tablesdb'
+                ? await this.loadTablesFirst(tablesDir, collectionsDir)
+                : await this.loadCollectionsAndTables(collectionsDir, tablesDir);
+            config.collections = items;
+            // Report what was loaded
+            if (fromTables > 0 && fromCollections > 0) {
+                MessageFormatter.success(`Loaded ${items.length} total items: ${fromCollections} from collections/, ${fromTables} from tables/`, { prefix: "Config" });
+            }
+            else if (fromCollections > 0) {
+                MessageFormatter.success(`Loaded ${fromCollections} collections from collections/`, { prefix: "Config" });
+            }
+            else if (fromTables > 0) {
+                MessageFormatter.success(`Loaded ${fromTables} tables from tables/`, { prefix: "Config" });
+            }
+            // Report conflicts
+            if (conflicts.length > 0) {
+                MessageFormatter.warning(`Found ${conflicts.length} naming conflicts`, { prefix: "Config" });
+                conflicts.forEach(conflict => {
+                    MessageFormatter.info(`  - '${conflict.name}': ${conflict.source1} (used) vs ${conflict.source2} (skipped)`, { prefix: "Config" });
+                });
+            }
             MessageFormatter.success(`Loaded YAML config from: ${yamlPath}`, {
                 prefix: "Config",
             });
@@ -377,6 +413,54 @@ export class ConfigLoaderService {
             conflicts,
         };
     }
+    /**
+     * Loads tables first (higher priority), then collections (backward compatibility)
+     * Used for TablesDB projects (>= 1.8.0)
+     * @param tablesDir Path to the tables directory
+     * @param collectionsDir Path to the collections directory
+     * @returns Loading result with items, counts, and conflicts
+     */
+    async loadTablesFirst(tablesDir, collectionsDir) {
+        const items = [];
+        const loadedNames = new Set();
+        const conflicts = [];
+        // Load from tables/ directory first (HIGHER priority for TablesDB)
+        if (fs.existsSync(tablesDir)) {
+            const tables = await this.loadTables(tablesDir, { markAsTablesDir: true });
+            for (const table of tables) {
+                const name = table.name || table.tableId || table.$id || "";
+                loadedNames.add(name);
+                items.push(table);
+            }
+        }
+        // Load from collections/ directory second (LOWER priority, backward compatibility)
+        if (fs.existsSync(collectionsDir)) {
+            const collections = await this.loadCollections(collectionsDir);
+            for (const collection of collections) {
+                const name = collection.name || collection.$id || "";
+                // Check for conflicts - tables win
+                if (loadedNames.has(name)) {
+                    conflicts.push({
+                        name,
+                        source1: "tables/",
+                        source2: "collections/",
+                    });
+                }
+                else {
+                    loadedNames.add(name);
+                    items.push(collection);
+                }
+            }
+        }
+        const fromTables = items.filter((item) => item._isFromTablesDir).length;
+        const fromCollections = items.filter((item) => !item._isFromTablesDir).length;
+        return {
+            items,
+            fromCollections,
+            fromTables,
+            conflicts,
+        };
+    }
     /**
      * Validates that a configuration file can be loaded
      * @param configPath Path to the configuration file

package/dist/setupCommands.d.ts

@@ -1 +1,58 @@
+import { type ApiMode } from "./utils/versionDetection.js";
+/**
+ * Terminology configuration for API mode-specific naming
+ */
+interface TerminologyConfig {
+    container: "table" | "collection";
+    containerName: "Table" | "Collection";
+    fields: "columns" | "attributes";
+    fieldName: "Column" | "Attribute";
+    security: "rowSecurity" | "documentSecurity";
+    schemaRef: "table.schema.json" | "collection.schema.json";
+    items: "rows" | "documents";
+}
+/**
+ * Detection result with source information
+ */
+interface ApiModeDetectionResult {
+    apiMode: ApiMode;
+    useTables: boolean;
+    detectionSource: "appwrite.json" | "server-version" | "default";
+    serverVersion?: string;
+}
+/**
+ * Get terminology configuration based on API mode
+ */
+export declare function getTerminologyConfig(useTables: boolean): TerminologyConfig;
+/**
+ * Detect API mode using multiple detection sources
+ * Priority: appwrite.json > server version > default (collections)
+ */
+export declare function detectApiMode(basePath: string): Promise<ApiModeDetectionResult>;
+/**
+ * Create directory structure for Appwrite project
+ */
+export declare function createProjectDirectories(basePath: string, useTables: boolean): {
+    appwriteFolder: string;
+    containerFolder: string;
+    schemaFolder: string;
+    yamlSchemaFolder: string;
+    dataFolder: string;
+};
+/**
+ * Create example YAML schema file with correct terminology
+ */
+export declare function createExampleSchema(containerFolder: string, terminology: TerminologyConfig): string;
+/**
+ * Create JSON schema for YAML validation
+ */
+export declare function createYamlValidationSchema(yamlSchemaFolder: string, useTables: boolean): string;
+/**
+ * Initialize a new Appwrite project with correct directory structure and terminology
+ */
+export declare function initProject(basePath?: string, forceApiMode?: 'legacy' | 'tablesdb'): Promise<void>;
+/**
+ * Create a new collection or table schema file
+ */
+export declare function createSchema(name: string, basePath?: string, forceApiMode?: 'legacy' | 'tablesdb'): Promise<void>;
 export {};