appwrite-utils-cli 1.5.1 → 1.6.0

package/dist/config/yamlConfig.js

@@ -3,11 +3,20 @@ import yaml from "js-yaml";
 import fs from "fs";
 import path from "path";
 import { AppwriteConfigSchema, RuntimeSchema, FunctionScopes, FunctionSpecifications, permissionsSchema, PermissionToAppwritePermission } from "appwrite-utils";
+import { shouldIgnoreDirectory } from "../utils/directoryUtils.js";
+import { MessageFormatter } from "../shared/messageFormatter.js";
 const YamlConfigSchema = z.object({
     appwrite: z.object({
         endpoint: z.string().default("https://cloud.appwrite.io/v1"),
         project: z.string(),
         key: z.string(),
+        // Session authentication support
+        sessionCookie: z.string().optional(),
+        authMethod: z.enum(["session", "apikey", "auto"]).optional().default("auto"),
+        sessionMetadata: z.object({
+            email: z.string().optional(),
+            expiresAt: z.string().optional(),
+        }).optional(),
     }),
     logging: z
         .object({
@@ -46,12 +55,14 @@ const YamlConfigSchema = z.object({
         outputDirectory: z.string().default("schemas"),
         yamlSchemaDirectory: z.string().default(".yaml_schemas"),
         collectionsDirectory: z.string().default("collections"),
+        tablesDirectory: z.string().default("tables"),
     })
         .optional()
         .default({
         outputDirectory: "schemas",
         yamlSchemaDirectory: ".yaml_schemas",
         collectionsDirectory: "collections",
+        tablesDirectory: "tables",
     }),
     migrations: z
         .object({
@@ -140,6 +151,10 @@ export const convertYamlToAppwriteConfig = (yamlConfig) => {
         appwriteEndpoint: yamlConfig.appwrite.endpoint,
         appwriteProject: yamlConfig.appwrite.project,
         appwriteKey: yamlConfig.appwrite.key,
+        // Session authentication support from YAML
+        sessionCookie: yamlConfig.appwrite.sessionCookie,
+        authMethod: yamlConfig.appwrite.authMethod || "auto",
+        sessionMetadata: yamlConfig.appwrite.sessionMetadata,
         apiMode: "auto", // Default to auto-detect for dual API support
         appwriteClient: null,
         logging: {
@@ -155,12 +170,12 @@ export const convertYamlToAppwriteConfig = (yamlConfig) => {
         enableMockData: yamlConfig.data.enableMockData,
         documentBucketId: yamlConfig.data.documentBucketId,
         usersCollectionName: yamlConfig.data.usersCollectionName,
-        useMigrations: yamlConfig.migrations.enabled,
         schemaConfig: {
             outputDirectory: yamlConfig.schemas.outputDirectory,
             yamlSchemaDirectory: yamlConfig.schemas.yamlSchemaDirectory,
             importDirectory: yamlConfig.data.importDirectory,
             collectionsDirectory: yamlConfig.schemas.collectionsDirectory || "collections",
+            tablesDirectory: yamlConfig.schemas.tablesDirectory || "tables",
         },
         databases: yamlConfig.databases.map((db) => ({
             $id: db.id,
@@ -226,6 +241,46 @@ export const convertYamlToAppwriteConfig = (yamlConfig) => {
     };
     return appwriteConfig;
 };
+/**
+ * Load YAML config with optional session preservation
+ * Maintains authentication priority: explicit session > YAML file > system prefs
+ */
+export const loadYamlConfigWithSession = async (configPath, sessionOptions) => {
+    try {
+        const fileContent = fs.readFileSync(configPath, "utf8");
+        const yamlData = yaml.load(fileContent);
+        const yamlConfig = YamlConfigSchema.parse(yamlData);
+        const appwriteConfig = convertYamlToAppwriteConfig(yamlConfig);
+        // Apply session preservation if provided (explicit overrides take priority)
+        if (sessionOptions) {
+            if (sessionOptions.sessionCookie) {
+                appwriteConfig.sessionCookie = sessionOptions.sessionCookie;
+            }
+            if (sessionOptions.authMethod) {
+                appwriteConfig.authMethod = sessionOptions.authMethod;
+            }
+            if (sessionOptions.sessionMetadata) {
+                appwriteConfig.sessionMetadata = sessionOptions.sessionMetadata;
+            }
+        }
+        return appwriteConfig;
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            MessageFormatter.error("YAML config validation failed", undefined, { prefix: "Config" });
+            error.issues.forEach((err) => {
+                MessageFormatter.error(`${err.path.join('.')} → ${err.message}`, undefined, { prefix: "Config" });
+            });
+        }
+        else {
+            MessageFormatter.error("Error loading YAML config", error instanceof Error ? error : undefined, { prefix: "Config" });
+            if (error instanceof Error && error.stack) {
+                MessageFormatter.debug("Stack trace", error.stack, { prefix: "Config" });
+            }
+        }
+        return null;
+    }
+};
 export const loadYamlConfig = async (configPath) => {
     try {
         const fileContent = fs.readFileSync(configPath, "utf8");
@@ -235,15 +290,15 @@ export const loadYamlConfig = async (configPath) => {
     }
     catch (error) {
         if (error instanceof z.ZodError) {
-            console.error("❌ YAML config validation failed:");
+            MessageFormatter.error("YAML config validation failed", undefined, { prefix: "Config" });
             error.issues.forEach((err) => {
-                console.error(`  ${err.path.join('.')} → ${err.message}`);
+                MessageFormatter.error(`${err.path.join('.')} → ${err.message}`, undefined, { prefix: "Config" });
             });
         }
         else {
-            console.error("❌ Error loading YAML config:", error instanceof Error ? error.message : error);
+            MessageFormatter.error("Error loading YAML config", error instanceof Error ? error : undefined, { prefix: "Config" });
             if (error instanceof Error && error.stack) {
-                console.error("Stack trace:", error.stack);
+                MessageFormatter.debug("Stack trace", error.stack, { prefix: "Config" });
             }
         }
         return null;
@@ -288,45 +343,6 @@ export const findYamlConfig = (startDir) => {
     }
     return null;
 };
-const shouldIgnoreDirectory = (dirName) => {
-    const ignoredDirs = [
-        'node_modules',
-        'dist',
-        'build',
-        'coverage',
-        '.next',
-        '.nuxt',
-        '.cache',
-        '.git',
-        '.svn',
-        '.hg',
-        '__pycache__',
-        '.pytest_cache',
-        '.mypy_cache',
-        'venv',
-        '.venv',
-        'env',
-        '.env',
-        'target',
-        'out',
-        'bin',
-        'obj',
-        '.vs',
-        '.vscode',
-        '.idea',
-        'temp',
-        'tmp',
-        '.tmp',
-        'logs',
-        'log',
-        '.DS_Store',
-        'Thumbs.db'
-    ];
-    return ignoredDirs.includes(dirName) ||
-        dirName.startsWith('.git') ||
-        dirName.startsWith('node_modules') ||
-        (dirName.startsWith('.') && dirName !== '.appwrite');
-};
 const findYamlConfigRecursive = (dir, depth = 0) => {
     // Limit search depth to prevent infinite recursion
     if (depth > 5) {
@@ -372,6 +388,9 @@ export const generateYamlConfigTemplate = (outputPath) => {
             endpoint: "https://cloud.appwrite.io/v1",
             project: "YOUR_PROJECT_ID",
             key: "YOUR_API_KEY",
+            authMethod: "auto",
+            // Optional session authentication (leave empty to use API key)
+            // sessionCookie: "session_cookie_from_appwrite_cli",
         },
         logging: {
             enabled: false,
@@ -394,6 +413,7 @@ export const generateYamlConfigTemplate = (outputPath) => {
             outputDirectory: "schemas",
             yamlSchemaDirectory: ".yaml_schemas",
             collectionsDirectory: "collections",
+            tablesDirectory: "tables",
         },
         migrations: {
             enabled: true,
@@ -406,14 +426,38 @@ export const generateYamlConfigTemplate = (outputPath) => {
         buckets: [],
         functions: [],
     };
-    const yamlContent = yaml.dump(template, {
+    let yamlContent = yaml.dump(template, {
         indent: 2,
         lineWidth: 120,
         sortKeys: false,
     });
-    // Add schema reference header
+    // Add inline comments to the schemas section
+    yamlContent = yamlContent.replace(/schemas:\s*\n(\s*)outputDirectory: schemas\n(\s*)yamlSchemaDirectory: \.yaml_schemas\n(\s*)collectionsDirectory: collections\n(\s*)tablesDirectory: tables/, `schemas:
+$1outputDirectory: schemas
+$2yamlSchemaDirectory: .yaml_schemas
+$3# Directory for legacy Databases API collection definitions
+$3collectionsDirectory: collections
+$4# Directory for new TablesDB API table definitions
+$4tablesDirectory: tables`);
+    // Add schema reference header and documentation
     const schemaReference = "# yaml-language-server: $schema=./.yaml_schemas/appwrite-config.schema.json\n";
-    const finalContent = schemaReference + "# Appwrite Project Configuration\n" + yamlContent;
+    const documentation = `# Appwrite Project Configuration
+#
+# Authentication Configuration:
+# - key: Standard API key authentication
+# - sessionCookie: Session cookie from Appwrite CLI authentication
+# - authMethod: "auto" (detects available method), "session" (prefer session), "apikey" (prefer API key)
+# - Priority: Explicit CLI args > YAML config > ~/.appwrite/prefs.json > Error
+#
+# Directory Configuration:
+# - collectionsDirectory: Use for legacy Databases API (default: "collections")
+# - tablesDirectory: Use for new TablesDB API (default: "tables")
+# - API mode is auto-detected based on server version, or set explicitly via apiMode
+#
+# For dual API support, both directories can coexist with different definitions
+
+`;
+    const finalContent = schemaReference + documentation + yamlContent;
     fs.writeFileSync(outputPath, finalContent, "utf8");
 };
 /**
@@ -429,6 +473,10 @@ export const writeYamlConfig = async (configPath, config) => {
                 endpoint: config.appwriteEndpoint,
                 project: config.appwriteProject,
                 key: config.appwriteKey,
+                // Include session authentication fields
+                sessionCookie: config.sessionCookie,
+                authMethod: config.authMethod || "auto",
+                sessionMetadata: config.sessionMetadata,
             },
             logging: {
                 enabled: config.logging?.enabled || false,
@@ -452,9 +500,10 @@ export const writeYamlConfig = async (configPath, config) => {
                 outputDirectory: config.schemaConfig?.outputDirectory || "schemas",
                 yamlSchemaDirectory: config.schemaConfig?.yamlSchemaDirectory || ".yaml_schemas",
                 collectionsDirectory: config.schemaConfig?.collectionsDirectory || "collections",
+                tablesDirectory: config.schemaConfig?.tablesDirectory || "tables",
             },
             migrations: {
-                enabled: config.useMigrations !== false,
+                enabled: true,
             },
             databases: config.databases?.map(db => ({
                 id: db.$id,
@@ -541,10 +590,10 @@ export const writeYamlConfig = async (configPath, config) => {
             finalContent = schemaReference + "# Appwrite Project Configuration\n" + yamlContent;
         }
         fs.writeFileSync(configPath, finalContent, "utf8");
-        console.log(`✅ Updated YAML configuration at ${configPath}`);
+        MessageFormatter.success(`Updated YAML configuration at ${configPath}`, { prefix: "Config" });
     }
     catch (error) {
-        console.error("❌ Error writing YAML config:", error instanceof Error ? error.message : error);
+        MessageFormatter.error("Error writing YAML config", error instanceof Error ? error : undefined, { prefix: "Config" });
         throw error;
     }
 };
@@ -600,10 +649,54 @@ export const addFunctionToYamlConfig = async (configPath, newFunction) => {
             finalContent = schemaLine + '\n' + updatedYamlContent;
         }
         fs.writeFileSync(configPath, finalContent, "utf8");
-        console.log(`✅ Added function "${newFunction.name}" to YAML config`);
+        MessageFormatter.success(`Added function "${newFunction.name}" to YAML config`, { prefix: "Config" });
     }
     catch (error) {
-        console.error("❌ Error adding function to YAML config:", error instanceof Error ? error.message : error);
+        MessageFormatter.error("Error adding function to YAML config", error instanceof Error ? error : undefined, { prefix: "Config" });
         throw error;
     }
 };
+/**
+ * Extract session options from AppwriteConfig for YAML operations
+ * Useful for preserving session state during config reloads
+ */
+export const extractSessionOptionsFromConfig = (config) => {
+    return {
+        sessionCookie: config.sessionCookie,
+        authMethod: config.authMethod,
+        sessionMetadata: config.sessionMetadata,
+    };
+};
+/**
+ * Create session-preserved YAML config operations
+ * Maintains authentication state during config file updates
+ */
+export const createSessionPreservingYamlConfig = (configPath, sessionOptions) => {
+    return {
+        load: () => loadYamlConfigWithSession(configPath, sessionOptions),
+        write: (config) => {
+            // Merge session options into config before writing
+            const enhancedConfig = {
+                ...config,
+                sessionCookie: sessionOptions.sessionCookie || config.sessionCookie,
+                authMethod: sessionOptions.authMethod || config.authMethod,
+                sessionMetadata: sessionOptions.sessionMetadata || config.sessionMetadata,
+            };
+            return writeYamlConfig(configPath, enhancedConfig);
+        },
+        addFunction: (func) => addFunctionToYamlConfig(configPath, func),
+    };
+};
+/**
+ * Determine if YAML config has session authentication configured
+ */
+export const hasYamlSessionAuth = (configPath) => {
+    try {
+        const fileContent = fs.readFileSync(configPath, "utf8");
+        const yamlData = yaml.load(fileContent);
+        return !!(yamlData?.appwrite?.sessionCookie && yamlData.appwrite.sessionCookie.trim());
+    }
+    catch (error) {
+        return false;
+    }
+};

package/dist/databases/methods.js

@@ -1,6 +1,7 @@
 import { Databases, Query } from "node-appwrite";
 import { delay, tryAwaitWithRetry } from "../utils/helperFunctions.js";
 import { fetchAllCollections } from "../collections/methods.js";
+import { MessageFormatter } from "../shared/messageFormatter.js";
 export const fetchAllDatabases = async (database) => {
     const databases = await tryAwaitWithRetry(async () => await database.list([Query.limit(25)]));
     const allDatabases = databases.databases;
@@ -21,11 +22,11 @@ export const fetchAllDatabases = async (database) => {
     return allDatabases;
 };
 export const wipeDatabase = async (database, databaseId) => {
-    console.log(`Wiping database: ${databaseId}`);
+    MessageFormatter.info(`Wiping database: ${databaseId}`, { prefix: "Database" });
     const existingCollections = await fetchAllCollections(databaseId, database);
     let collectionsDeleted = [];
     for (const { $id: collectionId, name } of existingCollections) {
-        console.log(`Deleting collection: ${collectionId}`);
+        MessageFormatter.info(`Deleting collection: ${collectionId}`, { prefix: "Database" });
         collectionsDeleted.push({ collectionId, collectionName: name });
         await tryAwaitWithRetry(async () => await database.deleteCollection(databaseId, collectionId));
         await delay(100);

package/dist/databases/setup.d.ts

@@ -1,6 +1,5 @@
 import { Databases, type Models } from "node-appwrite";
 import { type AppwriteConfig } from "appwrite-utils";
-export declare const setupMigrationDatabase: (config: AppwriteConfig) => Promise<void>;
 export declare const ensureDatabasesExist: (config: AppwriteConfig, databasesToEnsure?: Models.Database[]) => Promise<void>;
-export declare const wipeOtherDatabases: (database: Databases, databasesToKeep: Models.Database[], useMigrations?: boolean) => Promise<void>;
+export declare const wipeOtherDatabases: (database: Databases, databasesToKeep: Models.Database[]) => Promise<void>;
 export declare const ensureCollectionsExist: (config: AppwriteConfig, database: Models.Database, collectionsToEnsure?: Models.Collection[]) => Promise<void>;

package/dist/databases/setup.js

@@ -1,111 +1,33 @@
 import { Databases, Query } from "node-appwrite";
-import { createOrUpdateAttributeWithStatusCheck } from "../collections/attributes.js";
-import { getMigrationCollectionSchemas } from "../storage/schemas.js";
-import { areCollectionNamesSame, delay, toCamelCase, tryAwaitWithRetry, } from "../utils/index.js";
+import { tryAwaitWithRetry } from "../utils/index.js";
 import {} from "appwrite-utils";
 import { ulid } from "ulidx";
-export const setupMigrationDatabase = async (config) => {
-    if (!config.useMigrations) {
-        console.log("Migrations database disabled, skipping setup");
-        return;
-    }
-    console.log("---------------------------------");
-    console.log("Starting Migrations Setup");
-    console.log("---------------------------------");
-    const database = new Databases(config.appwriteClient);
-    if (!config.appwriteClient) {
-        throw new Error("Appwrite client is not initialized in the config");
-    }
-    let db;
-    const migrationCollectionsSetup = getMigrationCollectionSchemas();
-    try {
-        db = await tryAwaitWithRetry(async () => await database.get("migrations"), undefined, true);
-        console.log("Migrations database found");
-    }
-    catch (e) {
-        db = await tryAwaitWithRetry(async () => await database.create("migrations", "Migrations", true));
-        console.log("Migrations database created");
-    }
-    if (!db) {
-        console.error("Failed to create or retrieve the migrations database");
-        return;
-    }
-    for (const [collectionName, { collection, attributes }] of Object.entries(migrationCollectionsSetup)) {
-        const collectionId = toCamelCase(collectionName);
-        let collectionFound;
-        try {
-            collectionFound = await tryAwaitWithRetry(async () => await database.getCollection(db.$id, collectionId), undefined, true);
-            console.log(`Collection found: ${collectionId}`);
-        }
-        catch (e) {
-            console.log(`Collection not found: ${collectionId}`);
-            try {
-                collectionFound = await tryAwaitWithRetry(async () => await database.createCollection(db.$id, collectionId, collectionName, undefined, collection.documentSecurity, collection.enabled), undefined, true);
-                console.log(`Collection created: ${collectionId}`);
-            }
-            catch (createError) {
-                console.error(`Failed to create collection: ${collectionId}`, createError);
-                continue;
-            }
-        }
-        if (!collectionFound) {
-            console.error(`Failed to create or retrieve collection: ${collectionId}`);
-            continue;
-        }
-        for (const attribute of attributes) {
-            try {
-                await createOrUpdateAttributeWithStatusCheck(database, db.$id, collectionFound, attribute);
-                await delay(100);
-                console.log(`Attribute created/updated: ${attribute.key}`);
-            }
-            catch (attrError) {
-                console.error(`Failed to create/update attribute: ${attribute.key}`, attrError);
-            }
-        }
-    }
-    console.log("---------------------------------");
-    console.log("Migrations Setup Complete");
-    console.log("---------------------------------");
-};
+import { MessageFormatter } from "../shared/messageFormatter.js";
 export const ensureDatabasesExist = async (config, databasesToEnsure) => {
     if (!config.appwriteClient) {
         throw new Error("Appwrite client is not initialized in the config");
     }
     const database = new Databases(config.appwriteClient);
-    // Work on a shallow copy so we don't mutate caller-provided arrays
-    const databasesToCreate = [...(databasesToEnsure || config.databases || [])];
+    const databasesToCreate = databasesToEnsure || config.databases || [];
     if (!databasesToCreate.length) {
-        console.log("No databases to create");
+        MessageFormatter.info("No databases to create");
         return;
     }
     const existingDatabases = await tryAwaitWithRetry(async () => await database.list([Query.limit(500)]));
-    const migrationsDatabase = existingDatabases.databases.find((d) => d.name.toLowerCase().trim().replace(" ", "") === "migrations");
-    if (config.useMigrations && existingDatabases.databases.length !== 0 && migrationsDatabase) {
-        console.log("Creating all databases including migrations");
-        // Ensure migrations exists, but do not mutate the caller's array
-        if (!databasesToCreate.some((d) => d.$id === migrationsDatabase.$id)) {
-            databasesToCreate.push(migrationsDatabase);
-        }
-    }
     for (const db of databasesToCreate) {
         if (!existingDatabases.databases.some((d) => d.name === db.name)) {
             await tryAwaitWithRetry(async () => await database.create(db.$id || ulid(), db.name, true));
-            console.log(`${db.name} database created`);
+            MessageFormatter.success(`${db.name} database created`);
         }
     }
 };
-export const wipeOtherDatabases = async (database, databasesToKeep, useMigrations = true) => {
-    console.log(`Databases to keep: ${databasesToKeep.map(db => db.name).join(", ")}`);
+export const wipeOtherDatabases = async (database, databasesToKeep) => {
+    MessageFormatter.info(`Databases to keep: ${databasesToKeep.map(db => db.name).join(", ")}`);
     const allDatabases = await tryAwaitWithRetry(async () => await database.list([Query.limit(500)]));
-    const migrationsDatabase = allDatabases.databases.find((d) => d.name.toLowerCase().trim().replace(" ", "") === "migrations");
-    if (useMigrations && allDatabases.databases.length !== 0 && migrationsDatabase) {
-        console.log("Wiping all databases except migrations");
-        databasesToKeep.push(migrationsDatabase);
-    }
     for (const db of allDatabases.databases) {
         if (!databasesToKeep.some((d) => d.name === db.name)) {
             await tryAwaitWithRetry(async () => await database.delete(db.$id));
-            console.log(`Deleted database: ${db.name}`);
+            MessageFormatter.success(`Deleted database: ${db.name}`);
         }
     }
 };
@@ -117,7 +39,7 @@ export const ensureCollectionsExist = async (config, database, collectionsToEnsu
     for (const collection of collectionsToCreate) {
         if (!existingCollections.collections.some((c) => c.name === collection.name)) {
             await tryAwaitWithRetry(async () => await databaseClient.createCollection(database.$id, ulid(), collection.name, undefined, true, true));
-            console.log(`${collection.name} collection created in ${database.name}`);
+            MessageFormatter.success(`${collection.name} collection created in ${database.name}`);
         }
     }
 };

package/dist/examples/yamlTerminologyExample.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Example demonstrating YAML import/export with dual terminology support
+ *
+ * This example shows how to:
+ * 1. Generate YAML files for both collections and tables
+ * 2. Load and convert between terminologies
+ * 3. Validate terminology consistency
+ * 4. Migrate between formats
+ */
+import type { CollectionCreate } from "appwrite-utils";
+/**
+ * Example 1: Generate YAML templates for both collection and table formats
+ */
+export declare function generateTemplateExamples(outputDir: string): Promise<void>;
+/**
+ * Example 2: Convert existing collection definition to different formats
+ */
+export declare function convertCollectionFormats(collection: CollectionCreate): void;
+/**
+ * Example 3: Load and process YAML files with mixed terminologies
+ */
+export declare function processYamlFiles(baseDir: string): Promise<void>;
+/**
+ * Example 4: Migrate between terminologies
+ */
+export declare function migrateTerminology(baseDir: string): Promise<void>;
+/**
+ * Example 5: Validate terminology consistency
+ */
+export declare function validateTerminology(baseDir: string): Promise<void>;
+/**
+ * Example 6: Import configuration with terminology support
+ */
+export declare function importConfigurationExample(appwriteFolderPath: string): Promise<void>;
+/**
+ * Example 7: Manual terminology conversion
+ */
+export declare function manualTerminologyConversion(): void;
+/**
+ * Main example runner
+ */
+export declare function runYamlTerminologyExamples(outputDir: string): Promise<void>;