appwrite-utils-cli 0.10.85 → 1.0.1

package/src/config/yamlConfig.ts

@@ -0,0 +1,488 @@
+import { z } from "zod";
+import yaml from "js-yaml";
+import fs from "fs";
+import path from "path";
+import { AppwriteConfigSchema, type AppwriteConfig, RuntimeSchema, FunctionScopes, FunctionSpecifications, permissionsSchema, PermissionToAppwritePermission, type AppwriteFunction } from "appwrite-utils";
+
+const YamlConfigSchema = z.object({
+  appwrite: z.object({
+    endpoint: z.string().default("https://cloud.appwrite.io/v1"),
+    project: z.string(),
+    key: z.string(),
+  }),
+  logging: z
+    .object({
+      enabled: z.boolean().default(false),
+      level: z.enum(["error", "warn", "info", "debug"]).default("info"),
+      directory: z.string().optional(),
+      console: z.boolean().default(false),
+    })
+    .optional()
+    .default({ enabled: false, level: "info", console: false }),
+  backups: z
+    .object({
+      enabled: z.boolean().default(true),
+      interval: z.number().default(3600),
+      retention: z.number().default(30),
+      cleanup: z.boolean().default(true),
+    })
+    .optional()
+    .default({ enabled: true, interval: 3600, retention: 30, cleanup: true }),
+  data: z
+    .object({
+      enableMockData: z.boolean().default(false),
+      documentBucketId: z.string().default("documents"),
+      usersCollectionName: z.string().default("Members"),
+      importDirectory: z.string().default("importData"),
+    })
+    .optional()
+    .default({
+      enableMockData: false,
+      documentBucketId: "documents",
+      usersCollectionName: "Members",
+      importDirectory: "importData",
+    }),
+  schemas: z
+    .object({
+      outputDirectory: z.string().default("schemas"),
+      yamlSchemaDirectory: z.string().default(".yaml_schemas"),
+    })
+    .optional()
+    .default({
+      outputDirectory: "schemas",
+      yamlSchemaDirectory: ".yaml_schemas",
+    }),
+  migrations: z
+    .object({
+      enabled: z.boolean().default(true),
+    })
+    .optional()
+    .default({
+      enabled: true,
+    }),
+  databases: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        bucket: z
+          .object({
+            id: z.string(),
+            name: z.string(),
+            permissions: permissionsSchema,
+            fileSecurity: z.boolean().optional(),
+            enabled: z.boolean().optional(),
+            maximumFileSize: z.number().optional(),
+            allowedFileExtensions: z.array(z.string()).optional(),
+            compression: z.enum(["none", "gzip", "zstd"]).optional(),
+            encryption: z.boolean().optional(),
+            antivirus: z.boolean().optional(),
+          })
+          .optional(),
+      })
+    )
+    .optional()
+    .default([
+      { id: "dev", name: "Development" },
+      { id: "main", name: "Main" },
+      { id: "staging", name: "Staging" },
+    ]),
+  buckets: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        permissions: permissionsSchema,
+        fileSecurity: z.boolean().optional(),
+        enabled: z.boolean().optional(),
+        maximumFileSize: z.number().optional(),
+        allowedFileExtensions: z.array(z.string()).optional(),
+        compression: z.enum(["none", "gzip", "zstd"]).optional(),
+        encryption: z.boolean().optional(),
+        antivirus: z.boolean().optional(),
+      })
+    )
+    .optional()
+    .default([]),
+  functions: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        runtime: RuntimeSchema,
+        execute: z.array(z.string()).optional(),
+        events: z.array(z.string()).optional(),
+        schedule: z.string().optional(),
+        timeout: z.number().optional(),
+        enabled: z.boolean().optional(),
+        logging: z.boolean().optional(),
+        entrypoint: z.string().optional(),
+        commands: z.string().optional(),
+        scopes: z.array(FunctionScopes).optional(),
+        installationId: z.string().optional(),
+        providerRepositoryId: z.string().optional(),
+        providerBranch: z.string().optional(),
+        providerSilentMode: z.boolean().optional(),
+        providerRootDirectory: z.string().optional(),
+        templateRepository: z.string().optional(),
+        templateOwner: z.string().optional(),
+        templateRootDirectory: z.string().optional(),
+        templateBranch: z.string().optional(),
+        specification: FunctionSpecifications.optional(),
+      })
+    )
+    .optional()
+    .default([]),
+});
+
+export type YamlConfig = z.infer<typeof YamlConfigSchema>;
+
+export const convertYamlToAppwriteConfig = (yamlConfig: YamlConfig): AppwriteConfig => {
+  const appwriteConfig: AppwriteConfig = {
+    appwriteEndpoint: yamlConfig.appwrite.endpoint,
+    appwriteProject: yamlConfig.appwrite.project,
+    appwriteKey: yamlConfig.appwrite.key,
+    appwriteClient: null,
+    logging: {
+      enabled: yamlConfig.logging.enabled,
+      level: yamlConfig.logging.level,
+      logDirectory: yamlConfig.logging.directory,
+      console: yamlConfig.logging.console,
+    },
+    enableBackups: yamlConfig.backups.enabled,
+    backupInterval: yamlConfig.backups.interval,
+    backupRetention: yamlConfig.backups.retention,
+    enableBackupCleanup: yamlConfig.backups.cleanup,
+    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,
+    },
+    databases: yamlConfig.databases.map((db) => ({
+      $id: db.id,
+      name: db.name,
+      bucket: db.bucket
+        ? {
+            $id: db.bucket.id,
+            name: db.bucket.name,
+            $permissions: PermissionToAppwritePermission(db.bucket.permissions),
+            fileSecurity: db.bucket.fileSecurity || false,
+            enabled: db.bucket.enabled || true,
+            maximumFileSize: db.bucket.maximumFileSize || 30000000,
+            allowedFileExtensions: db.bucket.allowedFileExtensions || [],
+            compression: (db.bucket.compression as "none" | "gzip" | "zstd") || "none",
+            encryption: db.bucket.encryption || false,
+            antivirus: db.bucket.antivirus || false,
+          }
+        : undefined,
+    })),
+    buckets: yamlConfig.buckets.map((bucket) => ({
+      $id: bucket.id,
+      name: bucket.name,
+      $permissions: PermissionToAppwritePermission(bucket.permissions),
+      fileSecurity: bucket.fileSecurity || false,
+      enabled: bucket.enabled || true,
+      maximumFileSize: bucket.maximumFileSize || 30000000,
+      allowedFileExtensions: bucket.allowedFileExtensions || [],
+      compression: (bucket.compression as "none" | "gzip" | "zstd") || "none",
+      encryption: bucket.encryption || false,
+      antivirus: bucket.antivirus || false,
+    })),
+    functions: yamlConfig.functions?.map((func) => ({
+      $id: func.id,
+      name: func.name,
+      runtime: func.runtime,
+      execute: func.execute || [],
+      events: func.events || [],
+      schedule: func.schedule || "",
+      timeout: func.timeout || 15,
+      enabled: func.enabled || true,
+      logging: func.logging || true,
+      entrypoint: func.entrypoint || "",
+      commands: func.commands || "",
+      scopes: func.scopes || [],
+      installationId: func.installationId || "",
+      providerRepositoryId: func.providerRepositoryId || "",
+      providerBranch: func.providerBranch || "",
+      providerSilentMode: func.providerSilentMode || false,
+      providerRootDirectory: func.providerRootDirectory || "",
+      templateRepository: func.templateRepository || "",
+      templateOwner: func.templateOwner || "",
+      templateRootDirectory: func.templateRootDirectory || "",
+      templateBranch: func.templateBranch || "",
+      specification: func.specification || "s-0.5vcpu-512mb",
+    })),
+    collections: [],
+  };
+
+  return appwriteConfig;
+};
+
+export const loadYamlConfig = async (configPath: string): Promise<AppwriteConfig | null> => {
+  try {
+    const fileContent = fs.readFileSync(configPath, "utf8");
+    const yamlData = yaml.load(fileContent) as unknown;
+    
+    const yamlConfig = YamlConfigSchema.parse(yamlData);
+    return convertYamlToAppwriteConfig(yamlConfig);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("❌ YAML config validation failed:");
+      error.errors.forEach((err) => {
+        console.error(`  ${err.path.join('.')} → ${err.message}`);
+      });
+    } else {
+      console.error("❌ Error loading YAML config:", error instanceof Error ? error.message : error);
+      if (error instanceof Error && error.stack) {
+        console.error("Stack trace:", error.stack);
+      }
+    }
+    return null;
+  }
+};
+
+export const findYamlConfig = (startDir: string): string | null => {
+  // First check current directory for YAML configs
+  const possiblePaths = [
+    path.join(startDir, ".appwrite", "appwriteConfig.yaml"),
+    path.join(startDir, ".appwrite", "appwriteConfig.yml"),
+    path.join(startDir, ".appwrite", "config.yaml"),
+    path.join(startDir, ".appwrite", "config.yml"),
+    path.join(startDir, "appwrite.yaml"),
+    path.join(startDir, "appwrite.yml"),
+  ];
+
+  for (const configPath of possiblePaths) {
+    if (fs.existsSync(configPath)) {
+      return configPath;
+    }
+  }
+
+  // Recursively search subdirectories for .appwrite folders
+  const yamlConfigInSubdirs = findYamlConfigRecursive(startDir);
+  if (yamlConfigInSubdirs) {
+    return yamlConfigInSubdirs;
+  }
+
+  // Only check one level up to avoid infinite traversal
+  const parentDir = path.dirname(startDir);
+  if (parentDir !== startDir && path.basename(parentDir) !== 'node_modules') {
+    const parentPossiblePaths = [
+      path.join(parentDir, ".appwrite", "appwriteConfig.yaml"),
+      path.join(parentDir, ".appwrite", "appwriteConfig.yml"),
+      path.join(parentDir, "appwrite.yaml"),
+      path.join(parentDir, "appwrite.yml"),
+    ];
+
+    for (const configPath of parentPossiblePaths) {
+      if (fs.existsSync(configPath)) {
+        return configPath;
+      }
+    }
+  }
+
+  return null;
+};
+
+const shouldIgnoreDirectory = (dirName: string): boolean => {
+  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('.');
+};
+
+const findYamlConfigRecursive = (dir: string, depth: number = 0): string | null => {
+  // Limit search depth to prevent infinite recursion
+  if (depth > 5) {
+    return null;
+  }
+
+  if (shouldIgnoreDirectory(path.basename(dir))) {
+    return null;
+  }
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory() && !shouldIgnoreDirectory(entry.name)) {
+        const fullPath = path.join(dir, entry.name);
+        
+        // Check if this is an .appwrite directory
+        if (entry.name === ".appwrite") {
+          const configPaths = [
+            path.join(fullPath, "appwriteConfig.yaml"),
+            path.join(fullPath, "appwriteConfig.yml"),
+            path.join(fullPath, "config.yaml"),
+            path.join(fullPath, "config.yml"),
+          ];
+          
+          for (const configPath of configPaths) {
+            if (fs.existsSync(configPath)) {
+              return configPath;
+            }
+          }
+        }
+        
+        // Recurse into other directories with increased depth
+        const result = findYamlConfigRecursive(fullPath, depth + 1);
+        if (result) return result;
+      }
+    }
+  } catch (error) {
+    // Ignore directory access errors
+  }
+
+  return null;
+};
+
+export const generateYamlConfigTemplate = (outputPath: string) => {
+  const template: YamlConfig = {
+    appwrite: {
+      endpoint: "https://cloud.appwrite.io/v1",
+      project: "YOUR_PROJECT_ID",
+      key: "YOUR_API_KEY",
+    },
+    logging: {
+      enabled: false,
+      level: "info",
+      console: false,
+    },
+    backups: {
+      enabled: true,
+      interval: 3600,
+      retention: 30,
+      cleanup: true,
+    },
+    data: {
+      enableMockData: false,
+      documentBucketId: "documents",
+      usersCollectionName: "Members",
+      importDirectory: "importData",
+    },
+    schemas: {
+      outputDirectory: "schemas",
+      yamlSchemaDirectory: ".yaml_schemas",
+    },
+    migrations: {
+      enabled: true,
+    },
+    databases: [
+      { id: "dev", name: "Development" },
+      { id: "main", name: "Main" },
+      { id: "staging", name: "Staging" },
+    ],
+    buckets: [],
+    functions: [],
+  };
+
+  const yamlContent = yaml.dump(template, {
+    indent: 2,
+    lineWidth: 120,
+    sortKeys: false,
+  });
+
+  // Add schema reference header
+  const schemaReference = "# yaml-language-server: $schema=./.yaml_schemas/appwrite-config.schema.json\n";
+  const finalContent = schemaReference + "# Appwrite Project Configuration\n" + yamlContent;
+
+  fs.writeFileSync(outputPath, finalContent, "utf8");
+};
+
+/**
+ * Adds a new function to the YAML config file
+ * @param configPath Path to the YAML config file
+ * @param newFunction The function configuration to add
+ */
+export const addFunctionToYamlConfig = async (configPath: string, newFunction: AppwriteFunction): Promise<void> => {
+  try {
+    // Read current config
+    const fileContent = fs.readFileSync(configPath, "utf8");
+    const yamlData = yaml.load(fileContent) as any;
+    
+    // Initialize functions array if it doesn't exist
+    if (!yamlData.functions) {
+      yamlData.functions = [];
+    }
+    
+    // Convert AppwriteFunction to YAML format
+    const yamlFunction = {
+      id: newFunction.$id,
+      name: newFunction.name,
+      runtime: newFunction.runtime,
+      execute: newFunction.execute || ["any"],
+      events: newFunction.events || [],
+      schedule: newFunction.schedule || "",
+      timeout: newFunction.timeout || 15,
+      enabled: newFunction.enabled !== false,
+      logging: newFunction.logging !== false,
+      entrypoint: newFunction.entrypoint || "",
+      commands: newFunction.commands || "",
+      scopes: newFunction.scopes || [],
+      specification: newFunction.specification || "s-0.5vcpu-512mb"
+    };
+    
+    // Add new function
+    yamlData.functions.push(yamlFunction);
+    
+    // Write back to file
+    const updatedYamlContent = yaml.dump(yamlData, {
+      indent: 2,
+      lineWidth: 120,
+      sortKeys: false,
+    });
+    
+    // Preserve schema reference if it exists
+    const lines = fileContent.split('\n');
+    const schemaLine = lines.find(line => line.startsWith('# yaml-language-server:'));
+    let finalContent = updatedYamlContent;
+    
+    if (schemaLine) {
+      finalContent = schemaLine + '\n' + updatedYamlContent;
+    }
+    
+    fs.writeFileSync(configPath, finalContent, "utf8");
+    console.log(`✅ Added function "${newFunction.name}" to YAML config`);
+  } catch (error) {
+    console.error("❌ Error adding function to YAML config:", error instanceof Error ? error.message : error);
+    throw error;
+  }
+};

package/src/{migrations/setupDatabase.ts → databases/setup.ts}

@@ -1,6 +1,6 @@
 import { Databases, Query, type Models } from "node-appwrite";
 import { createOrUpdateAttribute } from "../collections/attributes.js";
-import { getMigrationCollectionSchemas } from "./backup.js";
+import { getMigrationCollectionSchemas } from "../storage/schemas.js";
 import {
   areCollectionNamesSame,
   delay,
@@ -11,6 +11,11 @@ import { type AppwriteConfig } from "appwrite-utils";
 import { ulid } from "ulidx";
 
 export const setupMigrationDatabase = async (config: AppwriteConfig) => {
+  if (!config.useMigrations) {
+    console.log("Migrations database disabled, skipping setup");
+    return;
+  }
+
   console.log("---------------------------------");
   console.log("Starting Migrations Setup");
   console.log("---------------------------------");
@@ -125,8 +130,8 @@ export const ensureDatabasesExist = async (config: AppwriteConfig, databasesToEn
   const migrationsDatabase = existingDatabases.databases.find(
     (d) => d.name.toLowerCase().trim().replace(" ", "") === "migrations"
   );
-  if (existingDatabases.databases.length !== 0 && migrationsDatabase) {
-    console.log("Creating all databases except migrations");
+  if (config.useMigrations && existingDatabases.databases.length !== 0 && migrationsDatabase) {
+    console.log("Creating all databases including migrations");
     databasesToCreate.push(migrationsDatabase);
   }
 
@@ -142,7 +147,8 @@ export const ensureDatabasesExist = async (config: AppwriteConfig, databasesToEn
 
 export const wipeOtherDatabases = async (
   database: Databases,
-  databasesToKeep: Models.Database[]
+  databasesToKeep: Models.Database[],
+  useMigrations: boolean = true
 ) => {
   console.log(`Databases to keep: ${databasesToKeep.map(db => db.name).join(", ")}`);
   const allDatabases = await tryAwaitWithRetry(
@@ -151,7 +157,7 @@ export const wipeOtherDatabases = async (
   const migrationsDatabase = allDatabases.databases.find(
     (d) => d.name.toLowerCase().trim().replace(" ", "") === "migrations"
   );
-  if (allDatabases.databases.length !== 0 && migrationsDatabase) {
+  if (useMigrations && allDatabases.databases.length !== 0 && migrationsDatabase) {
     console.log("Wiping all databases except migrations");
     databasesToKeep.push(migrationsDatabase);
   }

package/src/functions/methods.ts

@@ -5,12 +5,14 @@ import {
   Query,
   Runtime,
 } from "node-appwrite";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import {
   type AppwriteFunction,
   type FunctionScope,
   type Specification,
+  type Runtime as AppwriteUtilsRuntime,
 } from "appwrite-utils";
 import chalk from "chalk";
 import { extract as extractTar } from "tar";
@@ -136,7 +138,7 @@ export const updateFunctionSpecifications = async (
   try {
     const functionResponse = await updateFunction(client, {
       ...functionFound,
-      runtime: functionFound.runtime as Runtime,
+      runtime: functionFound.runtime as AppwriteUtilsRuntime,
       scopes: functionFound.scopes as FunctionScope[],
       specification: specification,
     });
@@ -193,12 +195,14 @@ export const updateFunction = async (
 };
 
 export const createFunctionTemplate = async (
-  templateType: "typescript-node" | "poetry" | "count-docs-in-collection",
+  templateType: "typescript-node" | "uv" | "count-docs-in-collection",
   functionName: string,
   basePath: string = "./functions"
 ) => {
   const functionPath = join(basePath, functionName);
-  const templatesPath = join(__dirname, "templates", templateType);
+  const currentFileUrl = import.meta.url;
+  const currentDir = dirname(fileURLToPath(currentFileUrl));
+  const templatesPath = join(currentDir, "templates", templateType);
 
   // Create function directory
   await fs.promises.mkdir(functionPath, { recursive: true });

package/src/functions/templates/count-docs-in-collection/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{functionName}}",
+  "version": "1.0.0",
+  "description": "Appwrite function to count documents in a collection",
+  "main": "src/main.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx src/main.ts"
+  },
+  "dependencies": {
+    "node-appwrite": "^13.0.0",
+    "appwrite-utils": "latest",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/functions/templates/count-docs-in-collection/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "checkJs": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleDetection": "force",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/src/functions/templates/typescript-node/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{functionName}}",
+  "version": "1.0.0",
+  "description": "Appwrite TypeScript Node.js function",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "node-appwrite": "^13.0.0",
+    "appwrite-utils": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/functions/templates/typescript-node/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "checkJs": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleDetection": "force",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}