appwrite-utils-cli 1.5.1 → 1.6.0

package/dist/utils/versionDetection.js

@@ -9,6 +9,8 @@
  * 2. Secondary: Health endpoint version check
  * 3. Fallback: Default to legacy mode for safety
  */
+import { logger } from '../shared/logging.js';
+import { MessageFormatter } from '../shared/messageFormatter.js';
 /**
  * Detects Appwrite API version and TablesDB support
  *
@@ -18,40 +20,117 @@
  * @returns Promise resolving to version detection result
  */
 export async function detectAppwriteVersion(endpoint, project, apiKey) {
+    const startTime = Date.now();
     // Clean endpoint URL
     const cleanEndpoint = endpoint.replace(/\/$/, '');
+    logger.info('Starting Appwrite version detection', {
+        endpoint: cleanEndpoint,
+        project,
+        operation: 'detectAppwriteVersion'
+    });
+    // STEP 1: Check server version FIRST
+    const serverVersion = await fetchServerVersion(cleanEndpoint);
+    if (serverVersion && !isVersionAtLeast(serverVersion, '1.8.0')) {
+        // Server < 1.8.0 doesn't support TablesDB
+        logger.info('Server version below 1.8.0 - using legacy adapter', {
+            serverVersion,
+            operation: 'detectAppwriteVersion'
+        });
+        return {
+            apiMode: 'legacy',
+            detectionMethod: 'health_check',
+            serverVersion,
+            confidence: 'high'
+        };
+    }
+    // STEP 2: Only proceed with endpoint probe if version >= 1.8.0 or version unknown
     // Try primary detection method: TablesDB endpoint probe
     try {
+        logger.debug('Attempting TablesDB endpoint probe', {
+            endpoint: cleanEndpoint,
+            serverVersion: serverVersion || 'unknown',
+            operation: 'detectAppwriteVersion'
+        });
+        const probeStartTime = Date.now();
         const tablesDbResult = await probeTablesDbEndpoint(cleanEndpoint, project, apiKey);
+        const probeDuration = Date.now() - probeStartTime;
         if (tablesDbResult.apiMode === 'tablesdb') {
+            logger.info('TablesDB detected via endpoint probe', {
+                endpoint: cleanEndpoint,
+                detectionMethod: tablesDbResult.detectionMethod,
+                confidence: tablesDbResult.confidence,
+                probeDuration,
+                totalDuration: Date.now() - startTime,
+                operation: 'detectAppwriteVersion'
+            });
             return tablesDbResult;
         }
     }
     catch (error) {
-        console.warn('TablesDB endpoint probe failed:', error instanceof Error ? error.message : 'Unknown error');
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        MessageFormatter.warning(`TablesDB endpoint probe failed: ${errorMessage}`, { prefix: "Version Detection" });
+        logger.warn('TablesDB endpoint probe failed', {
+            endpoint: cleanEndpoint,
+            error: errorMessage,
+            operation: 'detectAppwriteVersion'
+        });
     }
     // Try secondary detection method: SDK feature detection
     try {
+        logger.debug('Attempting SDK capability probe', {
+            endpoint: cleanEndpoint,
+            operation: 'detectAppwriteVersion'
+        });
+        const sdkProbeStartTime = Date.now();
         const sdkResult = await probeSdkCapabilities();
+        const sdkProbeDuration = Date.now() - sdkProbeStartTime;
         if (sdkResult.apiMode === 'tablesdb') {
+            logger.info('TablesDB detected via SDK capability probe', {
+                endpoint: cleanEndpoint,
+                detectionMethod: sdkResult.detectionMethod,
+                confidence: sdkResult.confidence,
+                sdkProbeDuration,
+                totalDuration: Date.now() - startTime,
+                operation: 'detectAppwriteVersion'
+            });
             return sdkResult;
         }
     }
     catch (error) {
-        console.warn('SDK capability probe failed:', error instanceof Error ? error.message : 'Unknown error');
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        MessageFormatter.warning(`SDK capability probe failed: ${errorMessage}`, { prefix: "Version Detection" });
+        logger.warn('SDK capability probe failed', {
+            endpoint: cleanEndpoint,
+            error: errorMessage,
+            operation: 'detectAppwriteVersion'
+        });
     }
     // Fallback to legacy mode
-    return {
+    const fallbackResult = {
         apiMode: 'legacy',
         detectionMethod: 'fallback',
         confidence: 'low'
     };
+    logger.info('Falling back to legacy mode', {
+        endpoint: cleanEndpoint,
+        totalDuration: Date.now() - startTime,
+        result: fallbackResult,
+        operation: 'detectAppwriteVersion'
+    });
+    return fallbackResult;
 }
 /**
  * Test TablesDB endpoint availability - most reliable detection method
  */
 async function probeTablesDbEndpoint(endpoint, project, apiKey) {
-    const response = await fetch(`${endpoint}/tablesdb/`, {
+    const startTime = Date.now();
+    const url = `${endpoint}/tablesdb/`;
+    logger.debug('Probing TablesDB endpoint', {
+        url,
+        project,
+        operation: 'probeTablesDbEndpoint'
+    });
+    const response = await fetch(url, {
         method: 'GET',
         headers: {
             'Content-Type': 'application/json',
@@ -61,17 +140,41 @@ async function probeTablesDbEndpoint(endpoint, project, apiKey) {
         // Short timeout for faster detection
         signal: AbortSignal.timeout(5000)
     });
-    if (response.ok || response.status === 404) {
-        // 200 = TablesDB available, 404 = endpoint exists but no tables
-        // Both indicate TablesDB support
-        return {
+    const duration = Date.now() - startTime;
+    logger.debug('TablesDB endpoint response received', {
+        url,
+        status: response.status,
+        statusText: response.statusText,
+        duration,
+        operation: 'probeTablesDbEndpoint'
+    });
+    if (response.ok) {
+        // ONLY 200 OK means TablesDB available
+        // 404 means endpoint doesn't exist (server < 1.8.0)
+        const result = {
             apiMode: 'tablesdb',
             detectionMethod: 'endpoint_probe',
             confidence: 'high'
         };
+        logger.info('TablesDB endpoint probe successful', {
+            url,
+            status: response.status,
+            result,
+            duration,
+            operation: 'probeTablesDbEndpoint'
+        });
+        return result;
     }
     // 501 Not Implemented or other errors = no TablesDB support
-    throw new Error(`TablesDB endpoint returned ${response.status}: ${response.statusText}`);
+    const error = new Error(`TablesDB endpoint returned ${response.status}: ${response.statusText}`);
+    logger.debug('TablesDB endpoint probe failed', {
+        url,
+        status: response.status,
+        statusText: response.statusText,
+        duration,
+        operation: 'probeTablesDbEndpoint'
+    });
+    throw error;
 }
 /**
  * SDK capability detection as secondary method
@@ -158,17 +261,50 @@ const detectionCache = new VersionDetectionCache();
  * @returns Promise resolving to version detection result
  */
 export async function detectAppwriteVersionCached(endpoint, project, apiKey, forceRefresh = false) {
+    const startTime = Date.now();
+    logger.debug('Version detection with cache requested', {
+        endpoint,
+        project,
+        forceRefresh,
+        operation: 'detectAppwriteVersionCached'
+    });
     // Check cache first (unless force refresh)
     if (!forceRefresh) {
         const cached = detectionCache.get(endpoint, project);
         if (cached) {
+            logger.info('Using cached version detection result', {
+                endpoint,
+                project,
+                cachedResult: cached,
+                operation: 'detectAppwriteVersionCached'
+            });
             return cached;
         }
+        logger.debug('No cached result found, performing fresh detection', {
+            endpoint,
+            project,
+            operation: 'detectAppwriteVersionCached'
+        });
+    }
+    else {
+        logger.debug('Force refresh requested, bypassing cache', {
+            endpoint,
+            project,
+            operation: 'detectAppwriteVersionCached'
+        });
     }
     // Perform fresh detection
     const result = await detectAppwriteVersion(endpoint, project, apiKey);
+    const totalDuration = Date.now() - startTime;
     // Cache the result
     detectionCache.set(endpoint, project, result);
+    logger.info('Version detection completed and cached', {
+        endpoint,
+        project,
+        result,
+        totalDuration,
+        operation: 'detectAppwriteVersionCached'
+    });
     return result;
 }
 /**

package/dist/utils/yamlConverter.d.ts

@@ -25,23 +25,73 @@ export interface YamlCollectionData {
         onDelete?: string;
         side?: string;
     }>;
+    columns?: Array<{
+        key: string;
+        type: string;
+        size?: number;
+        required?: boolean;
+        array?: boolean;
+        default?: any;
+        min?: number;
+        max?: number;
+        elements?: string[];
+        relatedTable?: string;
+        relationType?: string;
+        twoWay?: boolean;
+        twoWayKey?: string;
+        onDelete?: string;
+        side?: string;
+    }>;
     indexes?: Array<{
         key: string;
         type: string;
         attributes: string[];
+        columns?: string[];
         orders?: string[];
     }>;
     importDefs?: any[];
 }
+/**
+ * Configuration for terminology selection
+ */
+export interface YamlTerminologyConfig {
+    useTableTerminology: boolean;
+    entityType: 'collection' | 'table';
+    schemaPath?: string;
+}
 /**
  * Converts a Collection object to YAML format with proper schema reference
+ * Supports both collection and table terminology based on configuration
  */
-export declare function collectionToYaml(collection: Collection | CollectionCreate, schemaPath?: string): string;
+export declare function collectionToYaml(collection: Collection | CollectionCreate, config?: YamlTerminologyConfig): string;
 /**
  * Sanitizes a collection name for use as a filename
  */
 export declare function sanitizeFilename(name: string): string;
 /**
- * Generates the filename for a collection YAML file
+ * Generates the filename for a collection/table YAML file
+ */
+export declare function getCollectionYamlFilename(collection: Collection | CollectionCreate, useTableTerminology?: boolean): string;
+/**
+ * Converts column terminology back to attribute terminology for loading
+ */
+export declare function normalizeYamlData(yamlData: YamlCollectionData): YamlCollectionData;
+/**
+ * Determines if YAML data uses table terminology
+ */
+export declare function usesTableTerminology(yamlData: YamlCollectionData): boolean;
+/**
+ * Converts between attribute and column terminology
+ */
+export declare function convertTerminology(yamlData: YamlCollectionData, toTableTerminology: boolean): YamlCollectionData;
+/**
+ * Generates a template YAML file for collections or tables
+ */
+export declare function generateYamlTemplate(entityName: string, config: YamlTerminologyConfig): string;
+/**
+ * Generates example YAML files for both collection and table formats
  */
-export declare function getCollectionYamlFilename(collection: Collection | CollectionCreate): string;
+export declare function generateExampleYamls(entityName: string): {
+    collection: string;
+    table: string;
+};

package/dist/utils/yamlConverter.js

@@ -1,8 +1,14 @@
 import yaml from "js-yaml";
 /**
  * Converts a Collection object to YAML format with proper schema reference
+ * Supports both collection and table terminology based on configuration
  */
-export function collectionToYaml(collection, schemaPath = "../.yaml_schemas/collection.schema.json") {
+export function collectionToYaml(collection, config = {
+    useTableTerminology: false,
+    entityType: 'collection',
+    schemaPath: "../.yaml_schemas/collection.schema.json"
+}) {
+    const schemaPath = config.schemaPath || (config.useTableTerminology ? "../.yaml_schemas/table.schema.json" : "../.yaml_schemas/collection.schema.json");
     // Convert Collection to YamlCollectionData format
     const yamlData = {
         name: collection.name,
@@ -17,9 +23,9 @@ export function collectionToYaml(collection, schemaPath = "../.yaml_schemas/coll
             target: p.target
         }));
     }
-    // Convert attributes
+    // Convert attributes/columns based on terminology
     if (collection.attributes && collection.attributes.length > 0) {
-        yamlData.attributes = collection.attributes.map(attr => {
+        const attributeArray = collection.attributes.map(attr => {
             const yamlAttr = {
                 key: attr.key,
                 type: attr.type,
@@ -53,15 +59,31 @@ export function collectionToYaml(collection, schemaPath = "../.yaml_schemas/coll
                 yamlAttr.side = attr.side;
             return yamlAttr;
         });
+        // Use appropriate terminology
+        if (config.useTableTerminology) {
+            yamlData.columns = attributeArray;
+        }
+        else {
+            yamlData.attributes = attributeArray;
+        }
     }
-    // Convert indexes
+    // Convert indexes with appropriate field references
     if (collection.indexes && collection.indexes.length > 0) {
-        yamlData.indexes = collection.indexes.map(idx => ({
-            key: idx.key,
-            type: idx.type,
-            attributes: idx.attributes,
-            ...(idx.orders && idx.orders.length > 0 ? { orders: idx.orders } : {})
-        }));
+        yamlData.indexes = collection.indexes.map(idx => {
+            const indexData = {
+                key: idx.key,
+                type: idx.type,
+                ...(idx.orders && idx.orders.length > 0 ? { orders: idx.orders } : {})
+            };
+            // Use appropriate field terminology for index references
+            if (config.useTableTerminology) {
+                indexData.columns = idx.attributes;
+            }
+            else {
+                indexData.attributes = idx.attributes;
+            }
+            return indexData;
+        });
     }
     // Add import definitions if they exist
     if (collection.importDefs && collection.importDefs.length > 0) {
@@ -78,8 +100,10 @@ export function collectionToYaml(collection, schemaPath = "../.yaml_schemas/coll
         quotingType: '"',
         forceQuotes: false,
     });
+    // Determine the appropriate schema comment based on configuration
+    const entityType = config.useTableTerminology ? 'Table' : 'Collection';
     return `# yaml-language-server: $schema=${schemaPath}
-# Collection Definition: ${collection.name}
+# ${entityType} Definition: ${collection.name}
 ${yamlContent}`;
 }
 /**
@@ -89,8 +113,203 @@ export function sanitizeFilename(name) {
     return name.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 /**
- * Generates the filename for a collection YAML file
+ * Generates the filename for a collection/table YAML file
  */
-export function getCollectionYamlFilename(collection) {
+export function getCollectionYamlFilename(collection, useTableTerminology = false) {
     return `${sanitizeFilename(collection.name)}.yaml`;
 }
+/**
+ * Converts column terminology back to attribute terminology for loading
+ */
+export function normalizeYamlData(yamlData) {
+    const normalized = { ...yamlData };
+    // Convert columns to attributes if present
+    if (yamlData.columns && !yamlData.attributes) {
+        normalized.attributes = yamlData.columns.map(col => ({
+            ...col,
+            // Convert table-specific fields back to collection terminology
+            relatedCollection: col.relatedTable || col.relatedCollection,
+        }));
+        delete normalized.columns;
+    }
+    // Normalize index field references
+    if (normalized.indexes) {
+        normalized.indexes = normalized.indexes.map(idx => ({
+            ...idx,
+            attributes: idx.columns || idx.attributes,
+            // Remove columns field after normalization
+            columns: undefined
+        }));
+    }
+    return normalized;
+}
+/**
+ * Determines if YAML data uses table terminology
+ */
+export function usesTableTerminology(yamlData) {
+    return !!(yamlData.columns && yamlData.columns.length > 0) ||
+        !!(yamlData.indexes?.some(idx => !!idx.columns));
+}
+/**
+ * Converts between attribute and column terminology
+ */
+export function convertTerminology(yamlData, toTableTerminology) {
+    if (toTableTerminology) {
+        // Convert attributes to columns
+        const converted = { ...yamlData };
+        if (yamlData.attributes) {
+            converted.columns = yamlData.attributes.map(attr => ({
+                ...attr,
+                relatedTable: attr.relatedCollection,
+                relatedCollection: undefined
+            }));
+            delete converted.attributes;
+        }
+        // Convert index references
+        if (converted.indexes) {
+            converted.indexes = converted.indexes.map(idx => ({
+                ...idx,
+                columns: idx.attributes,
+                attributes: idx.attributes // Keep both for compatibility
+            }));
+        }
+        return converted;
+    }
+    else {
+        // Convert columns to attributes (normalize)
+        return normalizeYamlData(yamlData);
+    }
+}
+/**
+ * Generates a template YAML file for collections or tables
+ */
+export function generateYamlTemplate(entityName, config) {
+    const entityType = config.useTableTerminology ? 'table' : 'collection';
+    const fieldsKey = config.useTableTerminology ? 'columns' : 'attributes';
+    const relationKey = config.useTableTerminology ? 'relatedTable' : 'relatedCollection';
+    const indexFieldsKey = config.useTableTerminology ? 'columns' : 'attributes';
+    // Build template dynamically to handle computed property names
+    const fieldsArray = [
+        {
+            key: "id",
+            type: "string",
+            required: true,
+            size: 36
+        },
+        {
+            key: "name",
+            type: "string",
+            required: true,
+            size: 255
+        },
+        {
+            key: "description",
+            type: "string",
+            required: false,
+            size: 1000
+        },
+        {
+            key: "isActive",
+            type: "boolean",
+            required: true,
+            default: true
+        },
+        {
+            key: "createdAt",
+            type: "datetime",
+            required: true
+        },
+        {
+            key: "tags",
+            type: "string",
+            array: true,
+            required: false
+        },
+        {
+            key: "categoryId",
+            type: "relationship",
+            relationType: "manyToOne",
+            [relationKey]: "Categories",
+            required: false,
+            onDelete: "setNull"
+        }
+    ];
+    const indexesArray = [
+        {
+            key: "name_index",
+            type: "key",
+            [indexFieldsKey]: ["name"]
+        },
+        {
+            key: "active_created_index",
+            type: "key",
+            [indexFieldsKey]: ["isActive", "createdAt"],
+            orders: ["asc", "desc"]
+        },
+        {
+            key: "name_fulltext",
+            type: "fulltext",
+            [indexFieldsKey]: ["name", "description"]
+        }
+    ];
+    const template = {
+        name: entityName,
+        id: entityName.toLowerCase().replace(/\s+/g, '_'),
+        documentSecurity: false,
+        enabled: true,
+        permissions: [
+            {
+                permission: "read",
+                target: "users"
+            },
+            {
+                permission: "create",
+                target: "users"
+            },
+            {
+                permission: "update",
+                target: "users"
+            },
+            {
+                permission: "delete",
+                target: "users"
+            }
+        ],
+        importDefs: []
+    };
+    // Assign fields with correct property name
+    template[fieldsKey] = fieldsArray;
+    template.indexes = indexesArray;
+    // Generate YAML content
+    const yamlContent = yaml.dump(template, {
+        indent: 2,
+        lineWidth: 120,
+        sortKeys: false,
+        quotingType: '"',
+        forceQuotes: false,
+    });
+    // Add schema reference and documentation
+    const schemaPath = config.schemaPath ||
+        (config.useTableTerminology ? "../.yaml_schemas/table.schema.json" : "../.yaml_schemas/collection.schema.json");
+    const documentation = config.useTableTerminology
+        ? `# Table Definition: ${entityName}\n# This file defines a table for the new TablesDB API\n#\n# Key differences from Collections:\n# - Uses 'columns' instead of 'attributes'\n# - Uses 'relatedTable' instead of 'relatedCollection'\n# - Indexes reference 'columns' instead of 'attributes'\n#\n`
+        : `# Collection Definition: ${entityName}\n# This file defines a collection for the legacy Databases API\n#\n# Note: For new projects, consider using TablesDB API with table definitions\n#\n`;
+    return `# yaml-language-server: $schema=${schemaPath}\n${documentation}${yamlContent}`;
+}
+/**
+ * Generates example YAML files for both collection and table formats
+ */
+export function generateExampleYamls(entityName) {
+    const collectionYaml = generateYamlTemplate(entityName, {
+        useTableTerminology: false,
+        entityType: 'collection'
+    });
+    const tableYaml = generateYamlTemplate(entityName, {
+        useTableTerminology: true,
+        entityType: 'table'
+    });
+    return {
+        collection: collectionYaml,
+        table: tableYaml
+    };
+}

package/dist/utils/yamlLoader.d.ts

@@ -0,0 +1,70 @@
+import { type YamlCollectionData, type YamlTerminologyConfig } from "./yamlConverter.js";
+import type { CollectionCreate } from "appwrite-utils";
+/**
+ * Enhanced YAML loader with dual terminology support
+ */
+export declare class YamlLoader {
+    private baseDirectory;
+    constructor(baseDirectory: string);
+    /**
+     * Loads a YAML file with automatic terminology detection and normalization
+     */
+    loadCollectionYaml(filePath: string): Promise<{
+        data: YamlCollectionData;
+        originalTerminology: 'collection' | 'table';
+        normalized: YamlCollectionData;
+    }>;
+    /**
+     * Loads multiple YAML files from a directory with terminology support
+     */
+    loadDirectoryYamls(directoryPath: string, targetTerminology?: 'collection' | 'table'): Promise<{
+        collections: Array<{
+            filePath: string;
+            data: YamlCollectionData;
+            originalTerminology: 'collection' | 'table';
+            converted?: YamlCollectionData;
+        }>;
+        summary: {
+            total: number;
+            collectionFormat: number;
+            tableFormat: number;
+            converted: number;
+        };
+    }>;
+    /**
+     * Converts YAML data to CollectionCreate format for internal use
+     */
+    yamlToCollectionCreate(yamlData: YamlCollectionData): CollectionCreate;
+    /**
+     * Saves YAML data with specified terminology
+     */
+    saveCollectionYaml(filePath: string, data: YamlCollectionData, config: YamlTerminologyConfig): Promise<void>;
+    /**
+     * Migrates YAML files from one terminology to another
+     */
+    migrateTerminology(sourceDirectory: string, targetDirectory: string, toTableTerminology: boolean): Promise<{
+        migrated: number;
+        skipped: number;
+        errors: string[];
+    }>;
+    /**
+     * Validates YAML files for terminology consistency
+     */
+    validateTerminologyConsistency(directoryPath: string): Promise<{
+        isConsistent: boolean;
+        issues: Array<{
+            file: string;
+            issue: string;
+            severity: 'warning' | 'error';
+        }>;
+        summary: {
+            collectionFiles: number;
+            tableFiles: number;
+            mixedFiles: number;
+        };
+    }>;
+}
+/**
+ * Creates a YAML loader instance for the given base directory
+ */
+export declare function createYamlLoader(baseDirectory: string): YamlLoader;