appwrite-utils-cli 1.11.0 → 1.12.0

package/dist/examples/yamlTerminologyExample.js

@@ -0,0 +1,272 @@
+/**
+ * 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 { collectionToYaml, generateYamlTemplate, generateExampleYamls, convertTerminology, normalizeYamlData, usesTableTerminology } from "appwrite-utils-helpers";
+import { createYamlLoader } from "appwrite-utils-helpers";
+import { YamlImportIntegration } from "../migrations/yaml/YamlImportIntegration.js";
+import { createImportSchemas } from "../migrations/yaml/generateImportSchemas.js";
+import { CollectionCreateSchema } from "appwrite-utils";
+import fs from "fs";
+import path from "path";
+/**
+ * Example 1: Generate YAML templates for both collection and table formats
+ */
+export async function generateTemplateExamples(outputDir) {
+    console.log("🚀 Generating YAML template examples...");
+    // Ensure output directories exist
+    const collectionsDir = path.join(outputDir, "collections");
+    const tablesDir = path.join(outputDir, "tables");
+    [collectionsDir, tablesDir].forEach(dir => {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    });
+    // Generate schemas first
+    await createImportSchemas(outputDir);
+    // Generate examples for both formats
+    const examples = generateExampleYamls("Product");
+    // Save collection format
+    const collectionPath = path.join(collectionsDir, "Product.yaml");
+    fs.writeFileSync(collectionPath, examples.collection);
+    console.log(`✅ Generated collection YAML: ${collectionPath}`);
+    // Save table format
+    const tablePath = path.join(tablesDir, "Product.yaml");
+    fs.writeFileSync(tablePath, examples.table);
+    console.log(`✅ Generated table YAML: ${tablePath}`);
+}
+/**
+ * Example 2: Convert existing collection definition to different formats
+ */
+export function convertCollectionFormats(collection) {
+    console.log("🔄 Converting collection to different YAML formats...");
+    // Generate collection format YAML
+    const collectionConfig = {
+        useTableTerminology: false,
+        entityType: 'collection',
+        schemaPath: "../.yaml_schemas/collection.schema.json"
+    };
+    const collectionYaml = collectionToYaml(collection, collectionConfig);
+    console.log("📄 Collection Format YAML:");
+    console.log(collectionYaml);
+    console.log("");
+    // Generate table format YAML
+    const tableConfig = {
+        useTableTerminology: true,
+        entityType: 'table',
+        schemaPath: "../.yaml_schemas/table.schema.json"
+    };
+    const tableYaml = collectionToYaml(collection, tableConfig);
+    console.log("📄 Table Format YAML:");
+    console.log(tableYaml);
+}
+/**
+ * Example 3: Load and process YAML files with mixed terminologies
+ */
+export async function processYamlFiles(baseDir) {
+    console.log("📂 Processing YAML files with terminology support...");
+    const yamlLoader = createYamlLoader(baseDir);
+    // Load all YAML files from collections directory
+    const collectionsResult = await yamlLoader.loadDirectoryYamls("collections");
+    console.log(`📊 Collections Summary:`, collectionsResult.summary);
+    // Load all YAML files from tables directory
+    const tablesResult = await yamlLoader.loadDirectoryYamls("tables");
+    console.log(`📊 Tables Summary:`, tablesResult.summary);
+    // Process each file and show terminology detection
+    console.log("\\n🔍 File Analysis:");
+    [...collectionsResult.collections, ...tablesResult.collections].forEach(file => {
+        const terminology = file.originalTerminology;
+        const hasColumns = usesTableTerminology(file.data);
+        console.log(`  ${file.filePath}: ${terminology} format (uses table terminology: ${hasColumns})`);
+    });
+}
+/**
+ * Example 4: Migrate between terminologies
+ */
+export async function migrateTerminology(baseDir) {
+    console.log("🔄 Migrating between terminologies...");
+    const yamlLoader = createYamlLoader(baseDir);
+    // Migrate collections to table format
+    console.log("\\n📤 Migrating collections to table format...");
+    const collectionToTableResult = await yamlLoader.migrateTerminology("collections", "migrated/tables", true // to table terminology
+    );
+    console.log(`✅ Migration complete: ${collectionToTableResult.migrated} migrated, ${collectionToTableResult.skipped} skipped`);
+    if (collectionToTableResult.errors.length > 0) {
+        console.log(`❌ Errors:`, collectionToTableResult.errors);
+    }
+    // Migrate tables to collection format
+    console.log("\\n📤 Migrating tables to collection format...");
+    const tableToCollectionResult = await yamlLoader.migrateTerminology("tables", "migrated/collections", false // to collection terminology
+    );
+    console.log(`✅ Migration complete: ${tableToCollectionResult.migrated} migrated, ${tableToCollectionResult.skipped} skipped`);
+    if (tableToCollectionResult.errors.length > 0) {
+        console.log(`❌ Errors:`, tableToCollectionResult.errors);
+    }
+}
+/**
+ * Example 5: Validate terminology consistency
+ */
+export async function validateTerminology(baseDir) {
+    console.log("🔍 Validating terminology consistency...");
+    const yamlLoader = createYamlLoader(baseDir);
+    // Validate collections directory
+    const collectionsValidation = await yamlLoader.validateTerminologyConsistency("collections");
+    console.log("\\n📂 Collections Directory:");
+    console.log(`  Consistent: ${collectionsValidation.isConsistent}`);
+    console.log(`  Summary:`, collectionsValidation.summary);
+    if (collectionsValidation.issues.length > 0) {
+        console.log(`  Issues:`);
+        collectionsValidation.issues.forEach(issue => {
+            console.log(`    ${issue.severity.toUpperCase()}: ${issue.file} - ${issue.issue}`);
+        });
+    }
+    // Validate tables directory
+    const tablesValidation = await yamlLoader.validateTerminologyConsistency("tables");
+    console.log("\\n📂 Tables Directory:");
+    console.log(`  Consistent: ${tablesValidation.isConsistent}`);
+    console.log(`  Summary:`, tablesValidation.summary);
+    if (tablesValidation.issues.length > 0) {
+        console.log(`  Issues:`);
+        tablesValidation.issues.forEach(issue => {
+            console.log(`    ${issue.severity.toUpperCase()}: ${issue.file} - ${issue.issue}`);
+        });
+    }
+}
+/**
+ * Example 6: Import configuration with terminology support
+ */
+export async function importConfigurationExample(appwriteFolderPath) {
+    console.log("📥 Import configuration with terminology support...");
+    const yamlImportIntegration = new YamlImportIntegration(appwriteFolderPath);
+    // Initialize YAML import system
+    await yamlImportIntegration.initialize();
+    // Create example import configurations for both formats
+    console.log("\\n📝 Creating import configuration templates...");
+    // Collection format import config
+    await yamlImportIntegration.createFromTemplate("Users", "users.json", false, // collection terminology
+    "users-collection-import.yaml");
+    // Table format import config
+    await yamlImportIntegration.createFromTemplate("Users", "users.json", true, // table terminology
+    "users-table-import.yaml");
+    // Get statistics
+    const stats = await yamlImportIntegration.getStatistics();
+    console.log("\\n📊 Import Configuration Statistics:");
+    console.log(`  Total configurations: ${stats.totalConfigurations}`);
+    console.log(`  Collections with configs: ${stats.collectionsWithConfigs}`);
+    console.log(`  Total attribute mappings: ${stats.totalAttributeMappings}`);
+    console.log(`  Total relationship mappings: ${stats.totalRelationshipMappings}`);
+}
+/**
+ * Example 7: Manual terminology conversion
+ */
+export function manualTerminologyConversion() {
+    console.log("🔧 Manual terminology conversion example...");
+    // Sample YAML data with collection terminology
+    const collectionData = {
+        name: "Product",
+        id: "product",
+        attributes: [
+            {
+                key: "name",
+                type: "string",
+                required: true,
+                relatedCollection: "Categories"
+            }
+        ],
+        indexes: [
+            {
+                key: "name_index",
+                type: "key",
+                attributes: ["name"]
+            }
+        ]
+    };
+    console.log("\\n📝 Original (Collection format):");
+    console.log(JSON.stringify(collectionData, null, 2));
+    // Convert to table terminology
+    const tableData = convertTerminology(collectionData, true);
+    console.log("\\n🔄 Converted to Table format:");
+    console.log(JSON.stringify(tableData, null, 2));
+    // Convert back to collection terminology
+    const normalizedData = normalizeYamlData(tableData);
+    console.log("\\n↩️  Normalized back to Collection format:");
+    console.log(JSON.stringify(normalizedData, null, 2));
+    // Terminology detection
+    console.log("\\n🔍 Terminology Detection:");
+    console.log(`  Original uses table terminology: ${usesTableTerminology(collectionData)}`);
+    console.log(`  Converted uses table terminology: ${usesTableTerminology(tableData)}`);
+    console.log(`  Normalized uses table terminology: ${usesTableTerminology(normalizedData)}`);
+}
+/**
+ * Main example runner
+ */
+export async function runYamlTerminologyExamples(outputDir) {
+    console.log("🎯 Running YAML Terminology Examples\\n");
+    try {
+        // Example collection for demonstrations
+        const exampleCollectionInput = {
+            name: "Product",
+            $id: "product",
+            enabled: true,
+            documentSecurity: false,
+            $permissions: [],
+            attributes: [
+                {
+                    key: "name",
+                    type: "string",
+                    required: true,
+                    size: 255
+                },
+                {
+                    key: "price",
+                    type: "double",
+                    required: true,
+                    min: 0
+                },
+                {
+                    key: "categoryId",
+                    type: "relationship",
+                    relationType: "manyToOne",
+                    relatedCollection: "Categories",
+                    twoWay: false,
+                    onDelete: "setNull",
+                    required: false
+                }
+            ],
+            indexes: [
+                {
+                    key: "name_index",
+                    type: "key",
+                    attributes: ["name"]
+                }
+            ],
+            importDefs: []
+        };
+        const exampleCollection = CollectionCreateSchema.parse(exampleCollectionInput);
+        // Run examples
+        await generateTemplateExamples(outputDir);
+        console.log("\\n" + "=".repeat(60) + "\\n");
+        convertCollectionFormats(exampleCollection);
+        console.log("\\n" + "=".repeat(60) + "\\n");
+        await processYamlFiles(outputDir);
+        console.log("\\n" + "=".repeat(60) + "\\n");
+        await migrateTerminology(outputDir);
+        console.log("\\n" + "=".repeat(60) + "\\n");
+        await validateTerminology(outputDir);
+        console.log("\\n" + "=".repeat(60) + "\\n");
+        await importConfigurationExample(outputDir);
+        console.log("\\n" + "=".repeat(60) + "\\n");
+        manualTerminologyConversion();
+        console.log("\\n🎉 All examples completed successfully!");
+    }
+    catch (error) {
+        console.error("❌ Error running examples:", error);
+        throw error;
+    }
+}
+// Note: Functions are already exported above with their declarations

package/dist/functions/deployments.d.ts

@@ -0,0 +1,4 @@
+import { Client, type Models } from "node-appwrite";
+import { type AppwriteFunction } from "appwrite-utils";
+export declare const deployFunction: (client: Client, functionId: string, codePath: string, activate?: boolean, entrypoint?: string, commands?: string, ignored?: string[]) => Promise<Models.Deployment>;
+export declare const deployLocalFunction: (client: Client, functionName: string, functionConfig: AppwriteFunction, functionPath?: string, configDirPath?: string) => Promise<Models.Deployment>;

package/dist/functions/deployments.js

@@ -0,0 +1,146 @@
+import { Client, Functions, Runtime } from "node-appwrite";
+import { InputFile } from "node-appwrite/file";
+import { create as createTarball } from "tar";
+import { join, relative } from "node:path";
+import fs from "node:fs";
+import { platform } from "node:os";
+import {} from "appwrite-utils";
+import chalk from "chalk";
+import cliProgress from "cli-progress";
+import { execSync } from "child_process";
+import { createFunction, getFunction, updateFunction, updateFunctionSpecifications, } from "./methods.js";
+import ignore from "ignore";
+import { MessageFormatter } from "appwrite-utils-helpers";
+import { resolveFunctionDirectory, validateFunctionDirectory } from 'appwrite-utils-helpers';
+export const deployFunction = async (client, functionId, codePath, activate = true, entrypoint = "main.js", commands = "npm install", ignored = [
+    "node_modules",
+    ".git",
+    ".vscode",
+    ".DS_Store",
+    "__pycache__",
+    ".venv",
+]) => {
+    const functions = new Functions(client);
+    MessageFormatter.processing("Preparing function deployment...", { prefix: "Deployment" });
+    // Convert ignored patterns to lowercase for case-insensitive comparison
+    const ignoredLower = ignored.map((pattern) => pattern.toLowerCase());
+    const tarPath = join(process.cwd(), `function-${functionId}.tar.gz`);
+    // Verify codePath exists and is a directory
+    if (!fs.existsSync(codePath)) {
+        throw new Error(`Function directory not found at ${codePath}`);
+    }
+    const stats = await fs.promises.stat(codePath);
+    if (!stats.isDirectory()) {
+        throw new Error(`${codePath} is not a directory`);
+    }
+    MessageFormatter.processing(`Creating tarball from ${codePath}`, { prefix: "Deployment" });
+    const progressBar = new cliProgress.SingleBar({
+        format: "Uploading |" +
+            chalk.cyan("{bar}") +
+            "| {percentage}% | {value}/{total} Chunks",
+        barCompleteChar: "█",
+        barIncompleteChar: "░",
+        hideCursor: true,
+    });
+    await createTarball({
+        gzip: true,
+        file: tarPath,
+        cwd: codePath,
+        filter: (path, stat) => {
+            const relativePath = relative(codePath, join(codePath, path)).toLowerCase();
+            // Skip if path matches any ignored pattern
+            if (ignoredLower.some((pattern) => relativePath.startsWith(pattern) ||
+                relativePath.includes(`/${pattern}`) ||
+                relativePath.includes(`\\${pattern}`))) {
+                MessageFormatter.debug(`Ignoring ${path}`, undefined, { prefix: "Deployment" });
+                return false;
+            }
+            return true;
+        },
+    }, ["."] // This now only includes contents of codePath since we set cwd to codePath
+    );
+    const fileBuffer = await fs.promises.readFile(tarPath);
+    const fileObject = InputFile.fromBuffer(new Uint8Array(fileBuffer), `function-${functionId}.tar.gz`);
+    try {
+        MessageFormatter.processing("Creating deployment...", { prefix: "Deployment" });
+        // Start with 1 as default total since we don't know the chunk size yet
+        progressBar.start(1, 0);
+        const functionResponse = await functions.createDeployment(functionId, fileObject, activate, entrypoint, commands, (progress) => {
+            const chunks = progress.chunksUploaded;
+            const total = progress.chunksTotal;
+            if (chunks !== undefined && total !== undefined) {
+                // First chunk, initialize the bar with correct total
+                if (chunks === 0) {
+                    progressBar.start(total || 100, 0);
+                }
+                else {
+                    progressBar.update(chunks);
+                    // Check if upload is complete
+                    if (chunks === total) {
+                        progressBar.update(total);
+                        progressBar.stop();
+                        MessageFormatter.success("Upload complete!", { prefix: "Deployment" });
+                    }
+                }
+            }
+        });
+        // Ensure progress bar completes even if callback never fired
+        if (progressBar.getProgress() === 0) {
+            progressBar.update(1);
+            progressBar.stop();
+        }
+        await fs.promises.unlink(tarPath);
+        return functionResponse;
+    }
+    catch (error) {
+        progressBar.stop();
+        MessageFormatter.error("Deployment failed", error instanceof Error ? error : undefined, { prefix: "Deployment" });
+        throw error;
+    }
+};
+export const deployLocalFunction = async (client, functionName, functionConfig, functionPath, configDirPath) => {
+    let functionExists = true;
+    let functionThatExists;
+    try {
+        functionThatExists = await getFunction(client, functionConfig.$id);
+    }
+    catch (error) {
+        functionExists = false;
+    }
+    const resolvedConfigDir = configDirPath ?? process.cwd();
+    const resolvedPath = resolveFunctionDirectory(functionName, resolvedConfigDir, functionConfig.dirPath, functionPath);
+    if (!validateFunctionDirectory(resolvedPath)) {
+        throw new Error(`Function directory is invalid or missing required files: ${resolvedPath}`);
+    }
+    if (functionConfig.predeployCommands?.length) {
+        MessageFormatter.processing("Executing predeploy commands...", { prefix: "Deployment" });
+        const isWindows = platform() === "win32";
+        for (const command of functionConfig.predeployCommands) {
+            try {
+                MessageFormatter.debug(`Executing: ${command}`, undefined, { prefix: "Deployment" });
+                execSync(command, {
+                    cwd: resolvedPath,
+                    stdio: "inherit",
+                    shell: isWindows ? "cmd.exe" : "/bin/sh",
+                    windowsHide: true,
+                });
+            }
+            catch (error) {
+                MessageFormatter.error(`Failed to execute predeploy command: ${command}`, error instanceof Error ? error : undefined, { prefix: "Deployment" });
+                throw new Error(``);
+            }
+        }
+    }
+    // Only create function if it doesn't exist
+    if (!functionExists) {
+        await createFunction(client, functionConfig);
+    }
+    else {
+        MessageFormatter.processing("Updating function...", { prefix: "Deployment" });
+        await updateFunction(client, functionConfig);
+    }
+    const deployPath = functionConfig.deployDir
+        ? join(resolvedPath, functionConfig.deployDir)
+        : resolvedPath;
+    return deployFunction(client, functionConfig.$id, deployPath, true, functionConfig.entrypoint, functionConfig.commands, functionConfig.ignore);
+};

package/dist/functions/fnConfigDiscovery.d.ts

@@ -0,0 +1,3 @@
+import { type AppwriteFunction } from 'appwrite-utils';
+export declare function discoverFnConfigs(startDir: string): AppwriteFunction[];
+export declare function mergeDiscoveredFunctions(central?: AppwriteFunction[], discovered?: AppwriteFunction[]): AppwriteFunction[];

package/dist/functions/fnConfigDiscovery.js

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { homedir } from 'node:os';
+import { AppwriteFunctionSchema } from 'appwrite-utils';
+import { shouldIgnoreDirectory } from 'appwrite-utils-helpers';
+import { MessageFormatter } from 'appwrite-utils-helpers';
+function findGitRoot(startDir) {
+    let dir = path.resolve(startDir);
+    while (dir !== path.parse(dir).root) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.resolve(startDir);
+}
+function expandTilde(p) {
+    if (!p)
+        return p;
+    if (p === '~' || p.startsWith('~/'))
+        return p.replace(/^~(?=$|\/|\\)/, homedir());
+    return p;
+}
+export function discoverFnConfigs(startDir) {
+    const root = findGitRoot(startDir);
+    const results = [];
+    const visit = (dir, depth = 0) => {
+        if (depth > 5)
+            return; // cap depth
+        const base = path.basename(dir);
+        if (shouldIgnoreDirectory(base))
+            return;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Check for .fnconfig.yaml / .fnconfig.yml
+        for (const fname of ['.fnconfig.yaml', '.fnconfig.yml']) {
+            const cfgPath = path.join(dir, fname);
+            if (fs.existsSync(cfgPath)) {
+                try {
+                    const raw = fs.readFileSync(cfgPath, 'utf8');
+                    const data = yaml.load(raw);
+                    const parsed = AppwriteFunctionSchema.parse({
+                        $id: data.id || data.$id,
+                        name: data.name,
+                        runtime: data.runtime,
+                        execute: data.execute || [],
+                        events: data.events || [],
+                        schedule: data.schedule,
+                        timeout: data.timeout,
+                        enabled: data.enabled,
+                        logging: data.logging,
+                        entrypoint: data.entrypoint,
+                        commands: data.commands,
+                        scopes: data.scopes,
+                        installationId: data.installationId,
+                        providerRepositoryId: data.providerRepositoryId,
+                        providerBranch: data.providerBranch,
+                        providerSilentMode: data.providerSilentMode,
+                        providerRootDirectory: data.providerRootDirectory,
+                        templateRepository: data.templateRepository,
+                        templateOwner: data.templateOwner,
+                        templateRootDirectory: data.templateRootDirectory,
+                        templateVersion: data.templateVersion,
+                        specification: data.specification,
+                        dirPath: data.dirPath,
+                        predeployCommands: data.predeployCommands,
+                        deployDir: data.deployDir,
+                        ignore: data.ignore,
+                    });
+                    // Resolve dirPath relative to the config file directory
+                    let dirPath = parsed.dirPath || '.';
+                    dirPath = expandTilde(dirPath);
+                    if (!path.isAbsolute(dirPath))
+                        dirPath = path.resolve(path.dirname(cfgPath), dirPath);
+                    const merged = { ...parsed, dirPath };
+                    results.push(merged);
+                }
+                catch (e) {
+                    MessageFormatter.warning(`Failed to parse ${cfgPath}: ${e instanceof Error ? e.message : String(e)}`, { prefix: 'Functions' });
+                }
+            }
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                visit(path.join(dir, entry.name), depth + 1);
+        }
+    };
+    visit(root, 0);
+    return results;
+}
+export function mergeDiscoveredFunctions(central = [], discovered = []) {
+    const map = new Map();
+    for (const f of central)
+        if (f?.$id)
+            map.set(f.$id, f);
+    for (const f of discovered)
+        if (f?.$id)
+            map.set(f.$id, f); // discovered overrides
+    return Array.from(map.values());
+}

package/dist/functions/methods.d.ts

@@ -0,0 +1,16 @@
+import { Client } from "node-appwrite";
+import { type AppwriteFunction, type Specification } from "appwrite-utils";
+export declare const listFunctions: (client: Client, queries?: string[], search?: string) => Promise<import("node-appwrite").Models.FunctionList>;
+export declare const getFunction: (client: Client, functionId: string) => Promise<import("node-appwrite").Models.Function>;
+export declare const downloadLatestFunctionDeployment: (client: Client, functionId: string, basePath?: string) => Promise<{
+    path: string;
+    function: import("node-appwrite").Models.Function;
+    deployment: import("node-appwrite").Models.Deployment;
+}>;
+export declare const deleteFunction: (client: Client, functionId: string) => Promise<{}>;
+export declare const createFunction: (client: Client, functionConfig: AppwriteFunction) => Promise<import("node-appwrite").Models.Function>;
+export declare const updateFunctionSpecifications: (client: Client, functionId: string, specification: Specification) => Promise<import("node-appwrite").Models.Function | undefined>;
+export declare const listSpecifications: (client: Client) => Promise<import("node-appwrite").Models.SpecificationList>;
+export declare const listFunctionDeployments: (client: Client, functionId: string, queries?: string[]) => Promise<import("node-appwrite").Models.DeploymentList>;
+export declare const updateFunction: (client: Client, functionConfig: AppwriteFunction) => Promise<import("node-appwrite").Models.Function>;
+export declare const createFunctionTemplate: (templateType: "typescript-node" | "uv" | "count-docs-in-collection" | "hono-typescript", functionName: string, basePath?: string) => Promise<string>;