@njdamstra/appwrite-utils-cli 1.8.9

package/src/databases/methods.ts

@@ -0,0 +1,49 @@
+import { Databases, Query, type Models } 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: Databases
+): Promise<Models.Database[]> => {
+  const databases = await tryAwaitWithRetry(
+    async () => await database.list([Query.limit(25)])
+  );
+  const allDatabases = databases.databases;
+  if (allDatabases.length === 0) return [];
+  let lastDatabaseId = allDatabases[allDatabases.length - 1].$id;
+
+  while (databases.databases.length === 25) {
+    const moreDatabases = await database.list([
+      Query.limit(25),
+      Query.cursorAfter(lastDatabaseId),
+    ]);
+    allDatabases.push(...moreDatabases.databases);
+    if (moreDatabases.databases.length < 25) break;
+    lastDatabaseId =
+      moreDatabases.databases[moreDatabases.databases.length - 1].$id;
+  }
+
+  return allDatabases;
+};
+
+export const wipeDatabase = async (
+  database: Databases,
+  databaseId: string
+): Promise<{ collectionId: string; collectionName: string }[]> => {
+  MessageFormatter.info(`Wiping database: ${databaseId}`, { prefix: "Database" });
+  const existingCollections = await fetchAllCollections(databaseId, database);
+  let collectionsDeleted: { collectionId: string; collectionName: string }[] =
+    [];
+
+  for (const { $id: collectionId, name } of existingCollections) {
+    MessageFormatter.info(`Deleting collection: ${collectionId}`, { prefix: "Database" });
+    collectionsDeleted.push({ collectionId, collectionName: name });
+    await tryAwaitWithRetry(
+      async () => await database.deleteCollection(databaseId, collectionId)
+    );
+    await delay(100);
+  }
+
+  return collectionsDeleted;
+};

package/src/databases/setup.ts

@@ -0,0 +1,77 @@
+import { Databases, Query, type Models } from "node-appwrite";
+import { tryAwaitWithRetry } from "../utils/index.js";
+import { type AppwriteConfig } from "@njdamstra/appwrite-utils";
+import { ulid } from "ulidx";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+
+export const ensureDatabasesExist = async (config: AppwriteConfig, databasesToEnsure?: Models.Database[]) => {
+  if (!config.appwriteClient) {
+    throw new Error("Appwrite client is not initialized in the config");
+  }
+  const database = new Databases(config.appwriteClient);
+  const databasesToCreate = databasesToEnsure || config.databases || [];
+
+  if (!databasesToCreate.length) {
+    MessageFormatter.info("No databases to create");
+    return;
+  }
+
+  const existingDatabases = await tryAwaitWithRetry(
+    async () => await database.list([Query.limit(500)])
+  );
+
+  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)
+      );
+      MessageFormatter.success(`${db.name} database created`);
+    }
+  }
+};
+
+export const wipeOtherDatabases = async (
+  database: Databases,
+  databasesToKeep: Models.Database[]
+) => {
+  MessageFormatter.info(`Databases to keep: ${databasesToKeep.map(db => db.name).join(", ")}`);
+  const allDatabases = await tryAwaitWithRetry(
+    async () => await database.list([Query.limit(500)])
+  );
+  for (const db of allDatabases.databases) {
+    if (!databasesToKeep.some((d) => d.name === db.name)) {
+      await tryAwaitWithRetry(async () => await database.delete(db.$id));
+      MessageFormatter.success(`Deleted database: ${db.name}`);
+    }
+  }
+};
+
+export const ensureCollectionsExist = async (
+  config: AppwriteConfig,
+  database: Models.Database,
+  collectionsToEnsure?: Models.Collection[]
+) => {
+  const databaseClient = new Databases(config.appwriteClient!);
+  const collectionsToCreate = collectionsToEnsure || 
+    (config.collections ? config.collections : []);
+
+  const existingCollections = await tryAwaitWithRetry(
+    async () => await databaseClient.listCollections(database.$id, [Query.limit(500)])
+  );
+
+  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
+        )
+      );
+      MessageFormatter.success(`${collection.name} collection created in ${database.name}`);
+    }
+  }
+};

package/src/examples/yamlTerminologyExample.ts

@@ -0,0 +1,346 @@
+/**
+ * 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,
+  type YamlTerminologyConfig,
+  type YamlCollectionData
+} from "../utils/yamlConverter.js";
+import { createYamlLoader } from "../utils/yamlLoader.js";
+import { YamlImportIntegration } from "../migrations/yaml/YamlImportIntegration.js";
+import { createImportSchemas } from "../migrations/yaml/generateImportSchemas.js";
+import {
+  CollectionCreateSchema,
+  type CollectionCreate
+} from "@njdamstra/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: string): Promise<void> {
+  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: CollectionCreate): void {
+  console.log("🔄 Converting collection to different YAML formats...");
+
+  // Generate collection format YAML
+  const collectionConfig: YamlTerminologyConfig = {
+    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: YamlTerminologyConfig = {
+    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: string): Promise<void> {
+  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: string): Promise<void> {
+  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: string): Promise<void> {
+  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: string): Promise<void> {
+  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(): void {
+  console.log("🔧 Manual terminology conversion example...");
+
+  // Sample YAML data with collection terminology
+  const collectionData: YamlCollectionData = {
+    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: string): Promise<void> {
+  console.log("🎯 Running YAML Terminology Examples\\n");
+
+  try {
+    // Example collection for demonstrations
+    const exampleCollectionInput: CollectionCreate = {
+      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/src/functions/deployments.ts

@@ -0,0 +1,220 @@
+import { Client, Functions, Runtime, type Models } 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 { type AppwriteFunction, type Specification } from "@njdamstra/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 "../shared/messageFormatter.js";
+import { resolveFunctionDirectory, validateFunctionDirectory } from './pathResolution.js';
+
+export const deployFunction = async (
+  client: Client,
+  functionId: string,
+  codePath: string,
+  activate: boolean = true,
+  entrypoint: string = "index.js",
+  commands: string = "npm install",
+  ignored: string[] = [
+    "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: Client,
+  functionName: string,
+  functionConfig: AppwriteFunction,
+  functionPath?: string
+) => {
+  let functionExists = true;
+  let functionThatExists: Models.Function;
+  try {
+    functionThatExists = await getFunction(client, functionConfig.$id);
+  } catch (error) {
+    functionExists = false;
+  }
+
+  const configDirPath = process.cwd(); // TODO: This should be passed from caller
+  const resolvedPath = resolveFunctionDirectory(
+    functionName,
+    configDirPath,
+    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
+  );
+};