appwrite-utils-cli 1.4.1 → 1.5.1

package/src/utils/schemaStrings.ts

@@ -22,16 +22,23 @@ interface RelationshipDetail {
   isChild: boolean;
 }
 
-export class SchemaGenerator {
-  private relationshipMap = new Map<string, RelationshipDetail[]>();
-  private config: AppwriteConfig;
-  private appwriteFolderPath: string;
-
-  constructor(config: AppwriteConfig, appwriteFolderPath: string) {
-    this.config = config;
-    this.appwriteFolderPath = appwriteFolderPath;
-    this.extractRelationships();
-  }
+export class SchemaGenerator {
+  private relationshipMap = new Map<string, RelationshipDetail[]>();
+  private config: AppwriteConfig;
+  private appwriteFolderPath: string;
+
+  constructor(config: AppwriteConfig, appwriteFolderPath: string) {
+    this.config = config;
+    this.appwriteFolderPath = appwriteFolderPath;
+    this.extractRelationships();
+  }
+
+  private resolveCollectionName = (idOrName: string): string => {
+    const col = this.config.collections?.find(
+      (c) => c.$id === (idOrName as any) || c.name === idOrName
+    );
+    return col?.name ?? idOrName;
+  };
 
   public updateTsSchemas(): void {
     const collections = this.config.collections;
@@ -182,12 +189,12 @@ export class SchemaGenerator {
       if (!collection.attributes) {
         return;
       }
-      collection.attributes.forEach((attr) => {
-        if (attr.type === "relationship" && attr.twoWay && attr.twoWayKey) {
-          const relationshipAttr = attr as RelationshipAttribute;
-          let isArrayParent = false;
-          let isArrayChild = false;
-          switch (relationshipAttr.relationType) {
+      collection.attributes.forEach((attr) => {
+        if (attr.type === "relationship" && attr.twoWay && attr.twoWayKey) {
+          const relationshipAttr = attr as RelationshipAttribute;
+          let isArrayParent = false;
+          let isArrayChild = false;
+          switch (relationshipAttr.relationType) {
             case "oneToMany":
               isArrayParent = true;
               isArrayChild = false;
@@ -207,14 +214,14 @@ export class SchemaGenerator {
             default:
               break;
           }
-          this.addRelationship(
-            collection.name,
-            relationshipAttr.relatedCollection,
-            attr.key,
-            relationshipAttr.twoWayKey,
-            isArrayParent,
-            isArrayChild
-          );
+          this.addRelationship(
+            collection.name,
+            this.resolveCollectionName(relationshipAttr.relatedCollection),
+            attr.key,
+            relationshipAttr.twoWayKey!,
+            isArrayParent,
+            isArrayChild
+          );
           console.log(
             `Extracted relationship: ${attr.key}\n\t${collection.name} -> ${relationshipAttr.relatedCollection}, databaseId: ${collection.databaseId}`
           );
@@ -259,10 +266,10 @@ export class SchemaGenerator {
       return;
     }
     this.config.collections.forEach((collection) => {
-      const schemaString = this.createSchemaString(
-        collection.name,
-        collection.attributes
-      );
+      const schemaString = this.createSchemaStringV4(
+        collection.name,
+        collection.attributes
+      );
       const camelCaseName = toCamelCase(collection.name);
       const schemaPath = path.join(
         this.appwriteFolderPath,
@@ -274,117 +281,104 @@ export class SchemaGenerator {
     });
   }
 
-  createSchemaString = (name: string, attributes: Attribute[]): string => {
-    const pascalName = toPascalCase(name);
-    let imports = `import { z } from "zod";\n`;
+  // Zod v4 recursive getter-based schemas
+  createSchemaStringV4 = (name: string, attributes: Attribute[]): string => {
+    const pascalName = toPascalCase(name);
+    let imports = `import { z } from "zod";\n`;
 
     // Use the relationshipMap to find related collections
-    const relationshipDetails = this.relationshipMap.get(name) || [];
-    const relatedCollections = relationshipDetails
-      .filter((detail, index, self) => {
-        const uniqueKey = `${detail.parentCollection}-${detail.childCollection}-${detail.parentKey}-${detail.childKey}`;
-        return (
-          index ===
-          self.findIndex(
+    const relationshipDetails = this.relationshipMap.get(name) || [];
+    let relatedCollections = relationshipDetails
+      .filter((detail, index, self) => {
+        const uniqueKey = `${detail.parentCollection}-${detail.childCollection}-${detail.parentKey}-${detail.childKey}`;
+        return (
+          index ===
+          self.findIndex(
             (obj) =>
               `${obj.parentCollection}-${obj.childCollection}-${obj.parentKey}-${obj.childKey}` ===
               uniqueKey
           )
         );
       })
-      .map((detail) => {
-        const relatedCollectionName = detail.isChild
-          ? detail.parentCollection
-          : detail.childCollection;
-        const key = detail.isChild ? detail.childKey : detail.parentKey;
-        const isArray = detail.isArray ? "array" : "";
-        return [relatedCollectionName, key, isArray];
-      });
-
-    // Check if we have any relationships - if not, generate simple schema
-    const hasRelationships = relatedCollections.length > 0;
-    
-    let schemaString = `${imports}\n\n`;
-
-    if (!hasRelationships) {
-      // Simple case: no relationships, generate single schema directly
-      schemaString += `export const ${pascalName}Schema = z.object({\n`;
-      schemaString += `  $id: z.string(),\n`;
-      schemaString += `  $createdAt: z.string(),\n`;
-      schemaString += `  $updatedAt: z.string(),\n`;
-      schemaString += `  $permissions: z.array(z.string()),\n`;
-      for (const attribute of attributes) {
-        if (attribute.type === "relationship") {
-          continue;
-        }
-        schemaString += `  ${attribute.key}: ${this.typeToZod(attribute)},\n`;
-      }
-      schemaString += `});\n\n`;
-      schemaString += `export type ${pascalName} = z.infer<typeof ${pascalName}Schema>;\n\n`;
-    } else {
-      // Complex case: has relationships, generate BaseSchema + extended schema pattern
-      let relatedTypes = "";
-      let relatedTypesLazy = "";
-      let curNum = 0;
-      let maxNum = relatedCollections.length;
-      
-      relatedCollections.forEach((relatedCollection) => {
-        console.log(relatedCollection);
-        let relatedPascalName = toPascalCase(relatedCollection[0]);
-        let relatedCamelName = toCamelCase(relatedCollection[0]);
-        curNum++;
-        let endNameTypes = relatedPascalName;
-        let endNameLazy = `${relatedPascalName}Schema`;
-        if (relatedCollection[2] === "array") {
-          endNameTypes += "[]";
-          endNameLazy += ".array().default([])";
-        } else if (!(relatedCollection[2] === "array")) {
-          endNameTypes += " | null";
-          endNameLazy += ".nullish()";
-        }
-        imports += `import { ${relatedPascalName}Schema, type ${relatedPascalName} } from "./${relatedCamelName}";\n`;
-        relatedTypes += `${relatedCollection[1]}?: ${endNameTypes};\n`;
-        if (relatedTypes.length > 0 && curNum !== maxNum) {
-          relatedTypes += "  ";
-        }
-        relatedTypesLazy += `${relatedCollection[1]}: z.lazy(() => ${endNameLazy}),\n`;
-        if (relatedTypesLazy.length > 0 && curNum !== maxNum) {
-          relatedTypesLazy += "  ";
-        }
-      });
-
-      // Re-add imports after processing relationships
-      schemaString = `${imports}\n\n`;
-      
-      schemaString += `export const ${pascalName}SchemaBase = z.object({\n`;
-      schemaString += `  $id: z.string(),\n`;
-      schemaString += `  $createdAt: z.string(),\n`;
-      schemaString += `  $updatedAt: z.string(),\n`;
-      schemaString += `  $permissions: z.array(z.string()),\n`;
-      for (const attribute of attributes) {
-        if (attribute.type === "relationship") {
-          continue;
-        }
-        schemaString += `  ${attribute.key}: ${this.typeToZod(attribute)},\n`;
-      }
-      schemaString += `});\n\n`;
-      schemaString += `export type ${pascalName}Base = z.infer<typeof ${pascalName}SchemaBase>`;
-      if (relatedTypes.length > 0) {
-        schemaString += ` & {\n  ${relatedTypes}};\n\n`;
-      } else {
-        schemaString += `;\n\n`;
-      }
-      schemaString += `export const ${pascalName}Schema: z.ZodType<${pascalName}Base> = ${pascalName}SchemaBase`;
-      if (relatedTypes.length > 0) {
-        schemaString += `.extend({\n  ${relatedTypesLazy}});\n\n`;
-      } else {
-        schemaString += `;\n`;
-      }
-      schemaString += `export type ${pascalName} = z.infer<typeof ${pascalName}Schema>;\n\n`;
-    }
+      .map((detail) => {
+        const relatedCollectionName = detail.isChild
+          ? detail.parentCollection
+          : detail.childCollection;
+        const key = detail.isChild ? detail.childKey : detail.parentKey;
+        const isArray = detail.isArray ? "array" : "";
+        return [relatedCollectionName, key, isArray];
+      });
+
+    // Include one-way relationship attributes directly (no twoWayKey)
+    const oneWayRels: Array<[string, string, string]> = [];
+    for (const attr of attributes) {
+      if (attr.type === "relationship" && attr.relatedCollection) {
+        const relatedName = this.resolveCollectionName(attr.relatedCollection);
+        const isArray =
+          attr.relationType === "oneToMany" || attr.relationType === "manyToMany"
+            ? "array"
+            : "";
+        oneWayRels.push([relatedName, attr.key, isArray]);
+      }
+    }
+
+    // Merge and dedupe (by relatedName+key)
+    relatedCollections = [...relatedCollections, ...oneWayRels].filter(
+      (item, idx, self) =>
+        idx === self.findIndex((o) => `${o[0]}::${o[1]}` === `${item[0]}::${item[1]}`)
+    );
 
-    return schemaString;
-  };
+    const hasRelationships = relatedCollections.length > 0;
+
+    // Build imports for related collections
+    if (hasRelationships) {
+      const importLines = relatedCollections.map((rel) => {
+        const relatedPascalName = toPascalCase(rel[0]);
+        const relatedCamelName = toCamelCase(rel[0]);
+        return `import { ${relatedPascalName}Schema } from "./${relatedCamelName}";`;
+      });
+      const unique = Array.from(new Set(importLines));
+      imports += unique.join("\n") + (unique.length ? "\n" : "");
+    }
+
+    let schemaString = `${imports}\n`;
+
+    // Single object schema with recursive getters (Zod v4)
+    schemaString += `export const ${pascalName}Schema = z.object({\n`;
+    schemaString += `  $id: z.string(),\n`;
+    schemaString += `  $createdAt: z.string(),\n`;
+    schemaString += `  $updatedAt: z.string(),\n`;
+    schemaString += `  $permissions: z.array(z.string()),\n`;
+    for (const attribute of attributes) {
+      if (attribute.type === "relationship") continue;
+      schemaString += `  ${attribute.key}: ${this.typeToZod(attribute)},\n`;
+    }
+
+    // Add recursive getters for relationships (respect required flag)
+    relatedCollections.forEach((rel) => {
+      const relatedPascalName = toPascalCase(rel[0]);
+      const isArray = rel[2] === "array";
+      const key = String(rel[1]);
+      const attrMeta = attributes.find(a => a.key === key && a.type === "relationship");
+      const isRequired = !!attrMeta?.required;
+      let getterBody = "";
+      if (isArray) {
+        getterBody = isRequired
+          ? `${relatedPascalName}Schema.array()`
+          : `${relatedPascalName}Schema.array().nullish()`;
+      } else {
+        getterBody = isRequired
+          ? `${relatedPascalName}Schema`
+          : `${relatedPascalName}Schema.nullish()`;
+      }
+      schemaString += `  get ${key}(){\n    return ${getterBody}\n  },\n`;
+    });
+
+    schemaString += `});\n\n`;
+    schemaString += `export type ${pascalName} = z.infer<typeof ${pascalName}Schema>;\n\n`;
+
+    return schemaString;
+  };
 
   typeToZod = (attribute: Attribute) => {
     let baseSchemaCode = "";

package/src/utils/setupFiles.ts

@@ -1,7 +1,9 @@
 import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import path from "node:path";
 import type { AppwriteConfig } from "appwrite-utils";
-import { findAppwriteConfig } from "./loadConfigs.js";
+import { findAppwriteConfig } from "./loadConfigs.js";
+import { loadYamlConfig } from "../config/yamlConfig.js";
+import { fetchServerVersion, isVersionAtLeast } from "./versionDetection.js";
 import { findYamlConfig } from "../config/yamlConfig.js";
 import { ID } from "node-appwrite";
 import { ulid } from "ulidx";
@@ -265,16 +267,30 @@ export const setupDirsFiles = async (
   const appwriteSchemaFolder = path.join(appwriteFolder, "schemas");
   const appwriteYamlSchemaFolder = path.join(appwriteFolder, ".yaml_schemas");
   const appwriteDataFolder = path.join(appwriteFolder, "importData");
-  const collectionsFolder = path.join(appwriteFolder, "collections");
+  // Decide between collections or tables folder
+  let useTables = false;
+  try {
+    // Try reading YAML config if present to detect version
+    const yamlPath = findYamlConfig(basePath);
+    if (yamlPath) {
+      const cfg = await loadYamlConfig(yamlPath);
+      if (cfg) {
+        const ver = await fetchServerVersion(cfg.appwriteEndpoint);
+        if (isVersionAtLeast(ver || undefined, '1.8.0')) useTables = true;
+      }
+    }
+  } catch {}
+  const targetFolderName = useTables ? "tables" : "collections";
+  const collectionsFolder = path.join(appwriteFolder, targetFolderName);
 
   // Create directory structure
   if (!existsSync(appwriteFolder)) {
     mkdirSync(appwriteFolder, { recursive: true });
   }
 
-  if (!existsSync(collectionsFolder)) {
-    mkdirSync(collectionsFolder, { recursive: true });
-  }
+  if (!existsSync(collectionsFolder)) {
+    mkdirSync(collectionsFolder, { recursive: true });
+  }
 
   // Handle configuration file creation - YAML is now default
   if (useYaml) {

package/src/utils/versionDetection.ts

@@ -12,12 +12,12 @@
 
 export type ApiMode = 'legacy' | 'tablesdb';
 
-export interface VersionDetectionResult {
-  apiMode: ApiMode;
-  detectionMethod: 'endpoint_probe' | 'health_check' | 'fallback';
-  serverVersion?: string;
-  confidence: 'high' | 'medium' | 'low';
-}
+export interface VersionDetectionResult {
+  apiMode: ApiMode;
+  detectionMethod: 'endpoint_probe' | 'health_check' | 'fallback';
+  serverVersion?: string;
+  confidence: 'high' | 'medium' | 'low';
+}
 
 /**
  * Detects Appwrite API version and TablesDB support
@@ -55,13 +55,13 @@ export async function detectAppwriteVersion(
     console.warn('SDK capability probe failed:', error instanceof Error ? error.message : 'Unknown error');
   }
   
-  // Fallback to legacy mode
-  return {
-    apiMode: 'legacy',
-    detectionMethod: 'fallback',
-    confidence: 'low'
-  };
-}
+  // Fallback to legacy mode
+  return {
+    apiMode: 'legacy',
+    detectionMethod: 'fallback',
+    confidence: 'low'
+  };
+}
 
 /**
  * Test TablesDB endpoint availability - most reliable detection method
@@ -82,15 +82,15 @@ async function probeTablesDbEndpoint(
     signal: AbortSignal.timeout(5000)
   });
   
-  if (response.ok || response.status === 404) {
+  if (response.ok || response.status === 404) {
     // 200 = TablesDB available, 404 = endpoint exists but no tables
     // Both indicate TablesDB support
-    return {
-      apiMode: 'tablesdb',
-      detectionMethod: 'endpoint_probe',
-      confidence: 'high'
-    };
-  }
+    return {
+      apiMode: 'tablesdb',
+      detectionMethod: 'endpoint_probe',
+      confidence: 'high'
+    };
+  }
   
   // 501 Not Implemented or other errors = no TablesDB support
   throw new Error(`TablesDB endpoint returned ${response.status}: ${response.statusText}`);
@@ -262,4 +262,31 @@ export async function detectSdkSupport(): Promise<{
  */
 export function clearVersionDetectionCache(): void {
   detectionCache.clear();
-}
+}
+
+/**
+ * Fetch server version from /health/version (no auth required)
+ */
+export async function fetchServerVersion(endpoint: string): Promise<string | null> {
+  try {
+    const clean = endpoint.replace(/\/$/, '');
+    const res = await fetch(`${clean}/health/version`, { method: 'GET', signal: AbortSignal.timeout(5000) });
+    if (!res.ok) return null;
+    const data = await res.json().catch(() => null) as any;
+    const version = (data && (data.version || data.build || data.release)) ?? null;
+    return typeof version === 'string' ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Compare semantic versions (basic) */
+export function isVersionAtLeast(current: string | undefined, target: string): boolean {
+  if (!current) return false;
+  const toNums = (v: string) => v.split('.').map(n => parseInt(n, 10));
+  const [a1=0,a2=0,a3=0] = toNums(current);
+  const [b1,b2,b3] = toNums(target);
+  if (a1 !== b1) return a1 > b1;
+  if (a2 !== b2) return a2 > b2;
+  return a3 >= b3;
+}

package/src/utilsController.ts

@@ -27,13 +27,14 @@ import {
   wipeOtherDatabases,
   ensureCollectionsExist,
 } from "./databases/setup.js";
-import {
-  createOrUpdateCollections,
-  wipeDatabase,
-  generateSchemas,
-  fetchAllCollections,
-  wipeCollection,
-} from "./collections/methods.js";
+import {
+  createOrUpdateCollections,
+  wipeDatabase,
+  generateSchemas,
+  fetchAllCollections,
+  wipeCollection,
+} from "./collections/methods.js";
+import { wipeAllTables, wipeTableRows } from "./collections/methods.js";
 import {
   backupDatabase,
   ensureDatabaseConfigBucketsExist,
@@ -57,7 +58,8 @@ import {
   transferUsersLocalToRemote,
   type TransferOptions,
 } from "./migrations/transfer.js";
-import { getClient } from "./utils/getClientFromConfig.js";
+import { getClient } from "./utils/getClientFromConfig.js";
+import { getAdapterFromConfig } from "./utils/getClientFromConfig.js";
 import { fetchAllDatabases } from "./databases/methods.js";
 import {
   listFunctions,
@@ -413,14 +415,23 @@ export class UtilsController {
     MessageFormatter.success("All functions synchronized successfully!", { prefix: "Functions" });
   }
 
-  async wipeDatabase(database: Models.Database, wipeBucket: boolean = false) {
-    await this.init();
-    if (!this.database) throw new Error("Database not initialized");
-    await wipeDatabase(this.database, database.$id);
-    if (wipeBucket) {
-      await this.wipeBucketFromDatabase(database);
-    }
-  }
+  async wipeDatabase(database: Models.Database, wipeBucket: boolean = false) {
+    await this.init();
+    if (!this.database || !this.config) throw new Error("Database not initialized");
+    try {
+      const { adapter, apiMode } = await getAdapterFromConfig(this.config);
+      if (apiMode === 'tablesdb') {
+        await wipeAllTables(adapter, database.$id);
+      } else {
+        await wipeDatabase(this.database, database.$id);
+      }
+    } catch {
+      await wipeDatabase(this.database, database.$id);
+    }
+    if (wipeBucket) {
+      await this.wipeBucketFromDatabase(database);
+    }
+  }
 
   async wipeBucketFromDatabase(database: Models.Database) {
     // Check configured bucket in database config
@@ -448,14 +459,23 @@ export class UtilsController {
     }
   }
 
-  async wipeCollection(
-    database: Models.Database,
-    collection: Models.Collection
-  ) {
-    await this.init();
-    if (!this.database) throw new Error("Database not initialized");
-    await wipeCollection(this.database, database.$id, collection.$id);
-  }
+  async wipeCollection(
+    database: Models.Database,
+    collection: Models.Collection
+  ) {
+    await this.init();
+    if (!this.database || !this.config) throw new Error("Database not initialized");
+    try {
+      const { adapter, apiMode } = await getAdapterFromConfig(this.config);
+      if (apiMode === 'tablesdb') {
+        await wipeTableRows(adapter, database.$id, collection.$id);
+      } else {
+        await wipeCollection(this.database, database.$id, collection.$id);
+      }
+    } catch {
+      await wipeCollection(this.database, database.$id, collection.$id);
+    }
+  }
 
   async wipeDocumentStorage(bucketId: string) {
     await this.init();
@@ -581,10 +601,10 @@ export class UtilsController {
     await generator.updateConfig(this.config, isYamlProject);
   }
 
-  async syncDb(
-    databases: Models.Database[] = [],
-    collections: Models.Collection[] = []
-  ) {
+  async syncDb(
+    databases: Models.Database[] = [],
+    collections: Models.Collection[] = []
+  ) {
     await this.init();
     if (!this.database) {
       MessageFormatter.error("Database not initialized", undefined, { prefix: "Controller" });
@@ -594,10 +614,17 @@ export class UtilsController {
       const allDatabases = await fetchAllDatabases(this.database);
       databases = allDatabases;
     }
-    await this.ensureDatabasesExist(databases);
-    await this.ensureDatabaseConfigBucketsExist(databases);
-    await this.createOrUpdateCollectionsForDatabases(databases, collections);
-  }
+    // Ensure DBs exist (this may internally ensure migrations exists)
+    await this.ensureDatabasesExist(databases);
+    await this.ensureDatabaseConfigBucketsExist(databases);
+
+    // Do not push collections to the migrations database (prevents duplicate runs)
+    const dbsForCollections = databases.filter(
+      (db) => (this.config?.useMigrations ?? true) ? db.name.toLowerCase() !== "migrations" : true
+    );
+
+    await this.createOrUpdateCollectionsForDatabases(dbsForCollections, collections);
+  }
 
   getAppwriteFolderPath() {
     return this.appwriteFolderPath;