@njdamstra/appwrite-utils-cli 1.8.9

package/dist/shared/functionManager.js

@@ -0,0 +1,336 @@
+import { Client, Functions, Runtime } from "node-appwrite";
+import {} from "@njdamstra/appwrite-utils";
+import { join, relative, resolve, basename } from "node:path";
+import fs from "node:fs";
+import chalk from "chalk";
+import pLimit from "p-limit";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { MessageFormatter } from "./messageFormatter.js";
+/**
+ * Validates and filters events array for Appwrite functions
+ * - Filters out empty/invalid strings
+ * - Limits to 100 items maximum (Appwrite limit)
+ * - Returns empty array if input is invalid
+ */
+const validateEvents = (events) => {
+    if (!events || !Array.isArray(events))
+        return [];
+    return events
+        .filter(event => event && typeof event === 'string' && event.trim().length > 0)
+        .slice(0, 100);
+};
+// Concurrency limits
+const functionLimit = pLimit(5); // Moderate limit for function operations
+const queryLimit = pLimit(25); // Higher limit for read operations
+export class FunctionManager {
+    client;
+    functions;
+    constructor(client) {
+        this.client = client;
+        this.functions = new Functions(client);
+    }
+    /**
+     * Improved function directory detection with multiple strategies
+     */
+    async findFunctionDirectory(functionName, options = {}) {
+        const { searchPaths = [process.cwd()], caseSensitive = false, allowFuzzyMatch = true, verbose = false } = options;
+        if (verbose) {
+            MessageFormatter.info(`Searching for function: ${functionName}`, { prefix: "Functions" });
+        }
+        // Normalize function name for comparison
+        const normalizedName = caseSensitive ? functionName : functionName.toLowerCase();
+        const nameVariations = this.generateNameVariations(normalizedName);
+        // Strategy 1: Check standard locations first
+        const standardPaths = this.getStandardFunctionPaths(searchPaths, functionName);
+        for (const path of standardPaths) {
+            if (await this.isValidFunctionDirectory(path)) {
+                if (verbose) {
+                    MessageFormatter.success(`Found function at standard location: ${path}`, { prefix: "Functions" });
+                }
+                return path;
+            }
+        }
+        // Strategy 2: Recursive directory search with fuzzy matching
+        if (allowFuzzyMatch) {
+            for (const searchPath of searchPaths) {
+                const foundPath = await this.recursiveDirectorySearch(searchPath, nameVariations, { caseSensitive, verbose });
+                if (foundPath) {
+                    if (verbose) {
+                        MessageFormatter.success(`Found function via fuzzy search: ${foundPath}`, { prefix: "Functions" });
+                    }
+                    return foundPath;
+                }
+            }
+        }
+        if (verbose) {
+            MessageFormatter.warning(`Function directory not found: ${functionName}`, { prefix: "Functions" });
+        }
+        return null;
+    }
+    generateNameVariations(name) {
+        const variations = new Set([
+            name,
+            name.toLowerCase(),
+            name.replace(/\s+/g, "-"),
+            name.replace(/\s+/g, "_"),
+            name.replace(/[^a-z0-9]/gi, ""),
+            name.replace(/[-_\s]+/g, ""),
+            name.replace(/[-_\s]+/g, "-").toLowerCase(),
+            name.replace(/[-_\s]+/g, "_").toLowerCase(),
+        ]);
+        return variations;
+    }
+    getStandardFunctionPaths(searchPaths, functionName) {
+        const normalizedName = functionName.toLowerCase().replace(/\s+/g, "-");
+        const paths = [];
+        for (const basePath of searchPaths) {
+            paths.push(join(basePath, "functions", functionName), join(basePath, "functions", normalizedName), join(basePath, "src", "functions", functionName), join(basePath, "src", "functions", normalizedName), join(basePath, functionName), join(basePath, normalizedName), join(basePath, "appwrite", "functions", functionName), join(basePath, "appwrite", "functions", normalizedName));
+        }
+        return paths;
+    }
+    async recursiveDirectorySearch(searchPath, nameVariations, options) {
+        const { caseSensitive, verbose } = options;
+        try {
+            const stats = await fs.promises.stat(searchPath);
+            if (!stats.isDirectory())
+                return null;
+            const entries = await fs.promises.readdir(searchPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                // Skip common directories that won't contain functions
+                if (this.shouldSkipDirectory(entry.name))
+                    continue;
+                const entryPath = join(searchPath, entry.name);
+                // Check if this directory matches our function name
+                const entryNameToCheck = caseSensitive ? entry.name : entry.name.toLowerCase();
+                if (nameVariations.has(entryNameToCheck)) {
+                    if (await this.isValidFunctionDirectory(entryPath)) {
+                        return entryPath;
+                    }
+                }
+                // Recursively search subdirectories
+                const result = await this.recursiveDirectorySearch(entryPath, nameVariations, options);
+                if (result)
+                    return result;
+            }
+        }
+        catch (error) {
+            if (verbose) {
+                MessageFormatter.debug(`Skipping inaccessible directory: ${searchPath}`, undefined, { prefix: "Functions" });
+            }
+        }
+        return null;
+    }
+    shouldSkipDirectory(dirName) {
+        const skipDirs = new Set([
+            'node_modules',
+            '.git',
+            '.vscode',
+            '.idea',
+            'dist',
+            'build',
+            'coverage',
+            '.nyc_output',
+            'tmp',
+            'temp',
+            '.cache',
+            '__pycache__',
+            '.pytest_cache',
+            'venv',
+            '.venv',
+            'env',
+            '.env'
+        ]);
+        return skipDirs.has(dirName) || dirName.startsWith('.');
+    }
+    async isValidFunctionDirectory(path) {
+        try {
+            const stats = await fs.promises.stat(path);
+            if (!stats.isDirectory())
+                return false;
+            const files = await fs.promises.readdir(path);
+            // Check for common function indicators
+            const hasPackageJson = files.includes('package.json');
+            const hasMainFile = files.some(file => file.match(/^(index|main|app)\.(js|ts|py)$/i) ||
+                file === 'src' ||
+                file === 'lib');
+            const hasRequirements = files.includes('requirements.txt');
+            const hasPyProject = files.includes('pyproject.toml');
+            return hasPackageJson || hasMainFile || hasRequirements || hasPyProject;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Enhanced function deployment with better error handling and validation
+     */
+    async deployFunction(functionConfig, functionPath, options = {}) {
+        const { activate = true, entrypoint = functionConfig.entrypoint || "index.js", commands = functionConfig.commands || "npm install", ignored = ["node_modules", ".git", ".vscode", ".DS_Store", "__pycache__", ".venv"], verbose = false, forceRedeploy = false } = options;
+        return await functionLimit(async () => {
+            if (verbose) {
+                MessageFormatter.processing(`Deploying function: ${functionConfig.name}`, { prefix: "Functions" });
+                MessageFormatter.debug(`Path: ${functionPath}`, undefined, { prefix: "Functions" });
+                MessageFormatter.debug(`Entrypoint: ${entrypoint}`, undefined, { prefix: "Functions" });
+            }
+            // Validate function directory
+            if (!await this.isValidFunctionDirectory(functionPath)) {
+                throw new Error(`Invalid function directory: ${functionPath}`);
+            }
+            // Ensure function exists
+            let functionExists = false;
+            try {
+                await this.getFunction(functionConfig.$id);
+                functionExists = true;
+            }
+            catch (error) {
+                if (verbose) {
+                    MessageFormatter.info(`Function ${functionConfig.$id} does not exist, creating...`, { prefix: "Functions" });
+                }
+            }
+            // Create function if it doesn't exist
+            if (!functionExists) {
+                await this.createFunction(functionConfig, { verbose });
+            }
+            else if (forceRedeploy) {
+                await this.updateFunction(functionConfig, { verbose });
+            }
+            // Execute pre-deploy commands if specified
+            if (functionConfig.predeployCommands?.length) {
+                await this.executePredeployCommands(functionConfig.predeployCommands, functionPath, { verbose });
+            }
+            // Deploy the function
+            const deployment = await this.createDeployment(functionConfig.$id, functionPath, { activate, entrypoint, commands, ignored, verbose });
+            if (verbose) {
+                MessageFormatter.success(`Function ${functionConfig.name} deployed successfully`, { prefix: "Functions" });
+            }
+            return deployment;
+        });
+    }
+    async createFunction(functionConfig, options = {}) {
+        const { verbose = false } = options;
+        if (verbose) {
+            MessageFormatter.processing(`Creating function: ${functionConfig.name}`, { prefix: "Functions" });
+        }
+        return await tryAwaitWithRetry(async () => {
+            return await this.functions.create(functionConfig.$id, functionConfig.name, functionConfig.runtime, functionConfig.execute || [], functionConfig.events || [], functionConfig.schedule || "", functionConfig.timeout || 15, functionConfig.enabled !== false, functionConfig.logging !== false, functionConfig.entrypoint, functionConfig.commands, functionConfig.scopes || [], functionConfig.installationId, functionConfig.providerRepositoryId, functionConfig.providerBranch, functionConfig.providerSilentMode, functionConfig.providerRootDirectory);
+        });
+    }
+    async updateFunction(functionConfig, options = {}) {
+        const { verbose = false } = options;
+        if (verbose) {
+            MessageFormatter.processing(`Updating function: ${functionConfig.name}`, { prefix: "Functions" });
+        }
+        return await tryAwaitWithRetry(async () => {
+            return await this.functions.update(functionConfig.$id, functionConfig.name, functionConfig.runtime, functionConfig.execute || [], functionConfig.events || [], functionConfig.schedule || "", functionConfig.timeout || 15, functionConfig.enabled !== false, functionConfig.logging !== false, functionConfig.entrypoint, functionConfig.commands, functionConfig.scopes || [], functionConfig.installationId, functionConfig.providerRepositoryId, functionConfig.providerBranch, functionConfig.providerSilentMode, functionConfig.providerRootDirectory, functionConfig.specification);
+        });
+    }
+    async executePredeployCommands(commands, workingDir, options = {}) {
+        const { verbose = false } = options;
+        const { execSync } = await import("child_process");
+        const { platform } = await import("node:os");
+        if (verbose) {
+            MessageFormatter.processing("Executing pre-deploy commands...", { prefix: "Functions" });
+        }
+        const isWindows = platform() === "win32";
+        for (const command of commands) {
+            if (verbose) {
+                MessageFormatter.debug(`$ ${command}`, undefined, { prefix: "Functions" });
+            }
+            try {
+                execSync(command, {
+                    cwd: workingDir,
+                    stdio: verbose ? "inherit" : "pipe",
+                    shell: isWindows ? "cmd.exe" : "/bin/sh",
+                    windowsHide: true,
+                });
+            }
+            catch (error) {
+                MessageFormatter.error(`Failed to execute command: ${command}`, error, { prefix: "Functions" });
+                throw error;
+            }
+        }
+        if (verbose) {
+            MessageFormatter.success("Pre-deploy commands completed", { prefix: "Functions" });
+        }
+    }
+    async createDeployment(functionId, codePath, options = {}) {
+        const { activate = true, entrypoint = "index.js", commands = "npm install", ignored = [], verbose = false } = options;
+        const { InputFile } = await import("node-appwrite/file");
+        const { create: createTarball } = await import("tar");
+        const tarPath = join(process.cwd(), `function-${functionId}-${Date.now()}.tar.gz`);
+        try {
+            if (verbose) {
+                MessageFormatter.processing("Creating deployment archive...", { prefix: "Functions" });
+            }
+            // Create tarball
+            await createTarball({
+                gzip: true,
+                file: tarPath,
+                cwd: codePath,
+                filter: (path) => {
+                    const relativePath = relative(codePath, join(codePath, path)).toLowerCase();
+                    const shouldIgnore = ignored.some(pattern => relativePath.startsWith(pattern.toLowerCase()) ||
+                        relativePath.includes(`/${pattern.toLowerCase()}`) ||
+                        relativePath.includes(`\\${pattern.toLowerCase()}`));
+                    if (shouldIgnore && verbose) {
+                        MessageFormatter.debug(`Ignoring: ${path}`, undefined, { prefix: "Functions" });
+                    }
+                    return !shouldIgnore;
+                },
+            }, ["."]);
+            // Read and upload
+            const fileBuffer = await fs.promises.readFile(tarPath);
+            const fileObject = InputFile.fromBuffer(new Uint8Array(fileBuffer), `function-${functionId}.tar.gz`);
+            if (verbose) {
+                MessageFormatter.processing("Uploading deployment...", { prefix: "Functions" });
+            }
+            const deployment = await tryAwaitWithRetry(async () => {
+                return await this.functions.createDeployment(functionId, fileObject, activate, entrypoint, commands);
+            });
+            return deployment;
+        }
+        finally {
+            // Clean up tarball
+            try {
+                await fs.promises.unlink(tarPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+    async getFunction(functionId) {
+        return await queryLimit(() => tryAwaitWithRetry(async () => await this.functions.get(functionId)));
+    }
+    async listFunctions() {
+        return await queryLimit(() => tryAwaitWithRetry(async () => await this.functions.list()));
+    }
+    async deleteFunction(functionId) {
+        await functionLimit(() => tryAwaitWithRetry(async () => await this.functions.delete(functionId)));
+    }
+    /**
+     * Validate function configuration
+     */
+    validateFunctionConfig(functionConfig) {
+        const errors = [];
+        if (!functionConfig.$id) {
+            errors.push("Function ID is required");
+        }
+        if (!functionConfig.name) {
+            errors.push("Function name is required");
+        }
+        if (!functionConfig.runtime) {
+            errors.push("Function runtime is required");
+        }
+        if (!functionConfig.entrypoint) {
+            errors.push("Function entrypoint is required");
+        }
+        // Validate timeout
+        if (functionConfig.timeout && (functionConfig.timeout < 1 || functionConfig.timeout > 900)) {
+            errors.push("Function timeout must be between 1 and 900 seconds");
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}

package/dist/shared/indexManager.d.ts

@@ -0,0 +1,24 @@
+import { type Index, type CollectionCreate } from "@njdamstra/appwrite-utils";
+import { Databases, type Models } from "node-appwrite";
+export declare const indexesSame: (databaseIndex: Models.Index, configIndex: Index) => boolean;
+export declare const createOrUpdateIndex: (dbId: string, db: Databases, collectionId: string, index: Index, options?: {
+    verbose?: boolean;
+    forceRecreate?: boolean;
+}) => Promise<Models.Index | null>;
+export declare const createOrUpdateIndexes: (dbId: string, db: Databases, collectionId: string, indexes: Index[], options?: {
+    verbose?: boolean;
+    forceRecreate?: boolean;
+}) => Promise<void>;
+export declare const createUpdateCollectionIndexes: (db: Databases, dbId: string, collection: Models.Collection, collectionConfig: CollectionCreate, options?: {
+    verbose?: boolean;
+    forceRecreate?: boolean;
+}) => Promise<void>;
+export declare const deleteObsoleteIndexes: (db: Databases, dbId: string, collection: Models.Collection, collectionConfig: CollectionCreate, options?: {
+    verbose?: boolean;
+}) => Promise<void>;
+export declare const validateIndexConfiguration: (indexes: Index[], options?: {
+    verbose?: boolean;
+}) => {
+    valid: boolean;
+    errors: string[];
+};

package/dist/shared/indexManager.js

@@ -0,0 +1,151 @@
+import {} from "@njdamstra/appwrite-utils";
+import { Databases, IndexType, Query } from "node-appwrite";
+import { delay, tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import chalk from "chalk";
+import pLimit from "p-limit";
+import { MessageFormatter } from "./messageFormatter.js";
+// Concurrency limits for different operations
+const indexLimit = pLimit(3); // Low limit for index operations
+const queryLimit = pLimit(25); // Higher limit for read operations
+export const indexesSame = (databaseIndex, configIndex) => {
+    return (databaseIndex.key === configIndex.key &&
+        databaseIndex.type === configIndex.type &&
+        JSON.stringify(databaseIndex.attributes) === JSON.stringify(configIndex.attributes) &&
+        JSON.stringify(databaseIndex.orders) === JSON.stringify(configIndex.orders));
+};
+export const createOrUpdateIndex = async (dbId, db, collectionId, index, options = {}) => {
+    const { verbose = false, forceRecreate = false } = options;
+    return await indexLimit(async () => {
+        // Check for existing index
+        const existingIndexes = await queryLimit(() => tryAwaitWithRetry(async () => await db.listIndexes(dbId, collectionId, [Query.equal("key", index.key)])));
+        let shouldCreate = false;
+        let existingIndex;
+        if (existingIndexes.total > 0) {
+            existingIndex = existingIndexes.indexes[0];
+            if (forceRecreate || !indexesSame(existingIndex, index)) {
+                if (verbose) {
+                    MessageFormatter.warning(`Updating index ${index.key} in collection ${collectionId}`, { prefix: "Index Manager" });
+                }
+                // Delete existing index
+                await tryAwaitWithRetry(async () => {
+                    await db.deleteIndex(dbId, collectionId, existingIndex.key);
+                });
+                await delay(500); // Wait for deletion to complete
+                shouldCreate = true;
+            }
+            else {
+                if (verbose) {
+                    MessageFormatter.success(`Index ${index.key} is up to date`, { prefix: "Index Manager" });
+                }
+                return existingIndex;
+            }
+        }
+        else {
+            shouldCreate = true;
+            if (verbose) {
+                MessageFormatter.info(`Creating index ${index.key} in collection ${collectionId}`, { prefix: "Index Manager" });
+            }
+        }
+        if (shouldCreate) {
+            const newIndex = await tryAwaitWithRetry(async () => {
+                return await db.createIndex(dbId, collectionId, index.key, index.type, index.attributes, index.orders);
+            });
+            if (verbose) {
+                MessageFormatter.success(`Created index ${index.key}`, { prefix: "Index Manager" });
+            }
+            return newIndex;
+        }
+        return null;
+    });
+};
+export const createOrUpdateIndexes = async (dbId, db, collectionId, indexes, options = {}) => {
+    const { verbose = false } = options;
+    if (!indexes || indexes.length === 0) {
+        return;
+    }
+    if (verbose) {
+        MessageFormatter.info(`Processing ${indexes.length} indexes for collection ${collectionId}`, { prefix: "Index Manager" });
+    }
+    // Process indexes sequentially to avoid conflicts
+    for (const index of indexes) {
+        try {
+            await createOrUpdateIndex(dbId, db, collectionId, index, options);
+            // Add delay between index operations to prevent rate limiting
+            await delay(250);
+        }
+        catch (error) {
+            MessageFormatter.error(`Failed to process index ${index.key}`, error, { prefix: "Index Manager" });
+            throw error;
+        }
+    }
+    if (verbose) {
+        MessageFormatter.success(`Completed processing indexes for collection ${collectionId}`, { prefix: "Index Manager" });
+    }
+};
+export const createUpdateCollectionIndexes = async (db, dbId, collection, collectionConfig, options = {}) => {
+    if (!collectionConfig.indexes)
+        return;
+    await createOrUpdateIndexes(dbId, db, collection.$id, collectionConfig.indexes, options);
+};
+export const deleteObsoleteIndexes = async (db, dbId, collection, collectionConfig, options = {}) => {
+    const { verbose = false } = options;
+    const configIndexes = collectionConfig.indexes || [];
+    const configIndexKeys = new Set(configIndexes.map(index => index.key));
+    // Get all existing indexes
+    const existingIndexes = await queryLimit(() => tryAwaitWithRetry(async () => await db.listIndexes(dbId, collection.$id)));
+    // Find indexes that exist in the database but not in the config
+    const obsoleteIndexes = existingIndexes.indexes.filter((index) => !configIndexKeys.has(index.key));
+    if (obsoleteIndexes.length === 0) {
+        return;
+    }
+    if (verbose) {
+        MessageFormatter.warning(`Removing ${obsoleteIndexes.length} obsolete indexes from collection ${collection.name}`, { prefix: "Index Manager" });
+    }
+    // Process deletions with rate limiting
+    for (const index of obsoleteIndexes) {
+        await indexLimit(async () => {
+            await tryAwaitWithRetry(async () => {
+                await db.deleteIndex(dbId, collection.$id, index.key);
+            });
+        });
+        if (verbose) {
+            MessageFormatter.info(`Deleted obsolete index ${index.key}`, { prefix: "Index Manager" });
+        }
+        await delay(250);
+    }
+};
+export const validateIndexConfiguration = (indexes, options = {}) => {
+    const { verbose = false } = options;
+    const errors = [];
+    for (const index of indexes) {
+        // Validate required fields
+        if (!index.key) {
+            errors.push(`Index missing required 'key' field`);
+        }
+        if (!index.type) {
+            errors.push(`Index '${index.key}' missing required 'type' field`);
+        }
+        if (!index.attributes || index.attributes.length === 0) {
+            errors.push(`Index '${index.key}' missing required 'attributes' field`);
+        }
+        // Validate index type
+        const validTypes = Object.values(IndexType);
+        if (index.type && !validTypes.includes(index.type)) {
+            errors.push(`Index '${index.key}' has invalid type '${index.type}'. Valid types: ${validTypes.join(', ')}`);
+        }
+        // Validate orders array matches attributes length (if provided)
+        if (index.orders && index.attributes && index.orders.length !== index.attributes.length) {
+            errors.push(`Index '${index.key}' orders array length (${index.orders.length}) does not match attributes array length (${index.attributes.length})`);
+        }
+        // Check for duplicate keys within the same collection
+        const duplicateKeys = indexes.filter(i => i.key === index.key);
+        if (duplicateKeys.length > 1) {
+            errors.push(`Duplicate index key '${index.key}' found`);
+        }
+    }
+    if (verbose && errors.length > 0) {
+        MessageFormatter.error("Index validation errors", undefined, { prefix: "Index Manager" });
+        errors.forEach(error => MessageFormatter.error(`  - ${error}`, undefined, { prefix: "Index Manager" }));
+    }
+    return { valid: errors.length === 0, errors };
+};

package/dist/shared/jsonSchemaGenerator.d.ts

@@ -0,0 +1,50 @@
+import type { AppwriteConfig } from "@njdamstra/appwrite-utils";
+export interface JsonSchemaProperty {
+    type: string | string[];
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    enum?: any[];
+    items?: JsonSchemaProperty;
+    $ref?: string;
+    properties?: Record<string, JsonSchemaProperty>;
+    additionalProperties?: boolean;
+    required?: string[];
+    default?: any;
+    oneOf?: JsonSchemaProperty[];
+}
+export interface JsonSchema {
+    $schema: string;
+    $id: string;
+    title: string;
+    type: "object";
+    properties: Record<string, JsonSchemaProperty>;
+    required: string[];
+    additionalProperties: boolean;
+    definitions?: Record<string, JsonSchemaProperty>;
+}
+export declare class JsonSchemaGenerator {
+    private config;
+    private appwriteFolderPath;
+    private relationshipMap;
+    constructor(config: AppwriteConfig, appwriteFolderPath: string);
+    private resolveCollectionName;
+    private extractRelationships;
+    private attributeToJsonSchemaProperty;
+    private getBaseTypeSchema;
+    private createJsonSchema;
+    generateJsonSchemas(options?: {
+        outputFormat?: "json" | "typescript" | "both";
+        outputDirectory?: string;
+        verbose?: boolean;
+    }): void;
+    private generateTypeScriptSchema;
+    private generateIndexFile;
+    validateSchema(schema: JsonSchema): {
+        valid: boolean;
+        errors: string[];
+    };
+}