@njdamstra/appwrite-utils-cli 1.8.9 → 1.10.1

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@njdamstra/appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.8.9",
-  "main": "src/main.ts",
+  "version": "1.10.1",
+  "main": "dist/main.js",
   "type": "module",
   "repository": {
     "type": "git",
@@ -39,20 +39,23 @@
     "@types/inquirer": "^9.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/yargs": "^17.0.33",
-    "@njdamstra/appwrite-utils": "^1.6.5",
+    "@njdamstra/appwrite-utils": "^1.7.1",
+    "@njdamstra/appwrite-utils-helpers": "^0.1.2",
     "chalk": "^5.4.1",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
     "decimal.js": "^10.6.0",
     "es-toolkit": "^1.39.4",
+    "find-up": "^8.0.0",
     "ignore": "^6.0.2",
     "inquirer": "^9.3.7",
     "js-yaml": "^4.1.0",
     "jszip": "^3.10.1",
     "luxon": "^3.6.1",
     "nanostores": "^0.10.3",
-    "node-appwrite": "^20.2.1",
+    "node-appwrite": "^22.1.2",
     "p-limit": "^6.2.0",
+    "papaparse": "^5.5.3",
     "tar": "^7.4.3",
     "tsx": "^4.20.3",
     "ulidx": "^2.4.1",
@@ -68,6 +71,7 @@
     "@types/jszip": "^3.4.1",
     "@types/lodash": "^4.17.18",
     "@types/luxon": "^3.6.2",
+    "@types/papaparse": "^5.5.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.2",
     "typescript": "^5.8.3"

package/src/adapters/index.ts

@@ -1,37 +1,11 @@
 /**
- * Adapters Module - Unified Database API for Appwrite
- * 
- * This module exports all adapter classes and utilities for working with
- * both legacy Appwrite (collections/documents) and TablesDB (tables/rows) APIs.
+ * Adapters Module - Re-exported from appwrite-utils-helpers
+ *
+ * This module re-exports all adapter classes and utilities from the
+ * appwrite-utils-helpers package for backward compatibility.
+ *
+ * The adapters have been moved to the helpers package to make them
+ * available to other packages and reduce code duplication.
  */
 
-export { AdapterFactory, type AdapterFactoryConfig, type AdapterFactoryResult } from './AdapterFactory.js';
-export { 
-  type DatabaseAdapter, 
-  type CreateRowParams,
-  type UpdateRowParams,
-  type ListRowsParams,
-  type DeleteRowParams,
-  type CreateTableParams,
-  type UpdateTableParams,
-  type ListTablesParams,
-  type DeleteTableParams,
-  type GetTableParams,
-  type BulkCreateRowsParams,
-  type BulkUpsertRowsParams,
-  type BulkDeleteRowsParams,
-  type CreateIndexParams,
-  type ListIndexesParams,
-  type DeleteIndexParams,
-  type CreateAttributeParams,
-  type UpdateAttributeParams,
-  type DeleteAttributeParams,
-  type ApiResponse,
-  type AdapterMetadata,
-  BaseAdapter 
-} from './DatabaseAdapter.js';
-export { TablesDBAdapter } from './TablesDBAdapter.js';
-export { LegacyAdapter } from './LegacyAdapter.js';
-
-// Convenience exports
-export { createDatabaseAdapter, getApiCapabilities } from './AdapterFactory.js';
+export * from '@njdamstra/appwrite-utils-helpers';

package/src/backups/operations/bucketBackup.ts

@@ -3,8 +3,8 @@ import JSZip from "jszip";
 import { ID, Query } from "node-appwrite";
 import { InputFile } from "node-appwrite/file";
 import pLimit from "p-limit";
-import { MessageFormatter } from "../../shared/messageFormatter.js";
-import { logger } from "../../shared/logging.js";
+import { MessageFormatter } from '@njdamstra/appwrite-utils-helpers';
+import { logger } from '@njdamstra/appwrite-utils-helpers';
 import type { BucketManifest, BucketFileMetadata } from "../schemas/bucketManifest.js";
 import { ulid } from "ulidx";
 

package/src/backups/operations/collectionBackup.ts

@@ -2,12 +2,12 @@ import type { Storage, Databases, Models } from "node-appwrite";
 import { ID, Query } from "node-appwrite";
 import { InputFile } from "node-appwrite/file";
 import { ulid } from "ulidx";
-import { MessageFormatter } from "../../shared/messageFormatter.js";
-import { logger } from "../../shared/logging.js";
-import type { DatabaseAdapter } from "../../adapters/DatabaseAdapter.js";
+import { MessageFormatter } from '@njdamstra/appwrite-utils-helpers';
+import { logger } from '@njdamstra/appwrite-utils-helpers';
+import type { DatabaseAdapter } from '@njdamstra/appwrite-utils-helpers';
 import { tryAwaitWithRetry } from "@njdamstra/appwrite-utils";
 import { splitIntoBatches } from "../../shared/migrationHelpers.js";
-import { retryFailedPromises } from "../../utils/retryFailedPromises.js";
+import { retryFailedPromises } from "@njdamstra/appwrite-utils-helpers";
 import { ProgressManager } from "../../shared/progressManager.js";
 import { createBackupZip } from "../../storage/backupCompression.js";
 import {

package/src/backups/operations/comprehensiveBackup.ts

@@ -2,9 +2,9 @@ import type { Storage, Databases, Models } from "node-appwrite";
 import { ID } from "node-appwrite";
 import { InputFile } from "node-appwrite/file";
 import { ulid } from "ulidx";
-import { MessageFormatter } from "../../shared/messageFormatter.js";
-import { logger } from "../../shared/logging.js";
-import type { DatabaseAdapter } from "../../adapters/DatabaseAdapter.js";
+import { MessageFormatter } from '@njdamstra/appwrite-utils-helpers';
+import { logger } from '@njdamstra/appwrite-utils-helpers';
+import type { DatabaseAdapter } from '@njdamstra/appwrite-utils-helpers';
 import { backupDatabase } from "../../storage/methods.js";
 import { backupBucket } from "./bucketBackup.js";
 import {

package/src/backups/tracking/centralizedTracking.ts

@@ -1,6 +1,6 @@
-import type { DatabaseAdapter } from "../../adapters/DatabaseAdapter.js";
-import { logger } from "../../shared/logging.js";
-import { tryAwaitWithRetry } from "../../utils/helperFunctions.js";
+import type { DatabaseAdapter } from '@njdamstra/appwrite-utils-helpers';
+import { logger } from '@njdamstra/appwrite-utils-helpers';
+import { tryAwaitWithRetry } from "@njdamstra/appwrite-utils-helpers";
 import { Query, ID } from "node-appwrite";
 import {
   BACKUP_TABLE_ID,

package/src/cli/commands/configCommands.ts

@@ -1,20 +1,27 @@
 import inquirer from "inquirer";
-import { MessageFormatter } from "../../shared/messageFormatter.js";
+import fs from "fs";
+import path from "path";
+import { MessageFormatter } from '@njdamstra/appwrite-utils-helpers';
 import { migrateConfig } from "../../utils/configMigration.js";
 import {
   validateCollectionsTablesConfig,
   reportValidationResults,
-} from "../../config/configValidation.js";
+  ConfigManager,
+  findAppwriteConfig,
+  findYamlConfig,
+  YamlLoader,
+  resolveCollectionsDir,
+  resolveTablesDir
+} from "@njdamstra/appwrite-utils-helpers";
 import {
   createMigrationPlan,
   executeMigrationPlan,
   saveMigrationResult,
   type MigrationStrategy,
-} from "../../config/configMigration.js";
+} from '@njdamstra/appwrite-utils-helpers';
 import { createEmptyCollection } from "../../utils/setupFiles.js";
 import chalk from "chalk";
 import type { InteractiveCLI } from "../../interactiveCLI.js";
-import { ConfigManager } from "../../config/ConfigManager.js";
 import { UtilsController } from "../../utilsController.js";
 
 export const configCommands = {
@@ -56,7 +63,7 @@ export const configCommands = {
         return;
       }
 
-      const { validateCollectionsTablesConfig, reportValidationResults } = await import("../../config/configValidation.js");
+      const { validateCollectionsTablesConfig, reportValidationResults } = await import("@njdamstra/appwrite-utils-helpers");
       const validation = validateCollectionsTablesConfig(config);
 
       reportValidationResults(validation, { verbose: true });
@@ -78,6 +85,9 @@ export const configCommands = {
 
       await (cli as any).initControllerIfNeeded();
 
+      const currentDir = (cli as any).currentDir;
+      const yamlConfigPath = findYamlConfig(currentDir);
+
       // Ensure config is properly loaded with YAML collections
       if (!(cli as any).controller?.config) {
         MessageFormatter.error("No configuration found", undefined, { prefix: "Migration" });
@@ -90,8 +100,6 @@ export const configCommands = {
         return;
       }
 
-      const { createMigrationPlan, executeMigrationPlan, saveMigrationResult } = await import("../../config/configMigration.js");
-
       // Get user's migration strategy preference
       const { strategy } = await inquirer.prompt([
         {
@@ -106,6 +114,60 @@ export const configCommands = {
         }
       ]);
 
+      if (yamlConfigPath) {
+        const appwriteDir = path.dirname(yamlConfigPath);
+        const collectionsDir = resolveCollectionsDir(appwriteDir);
+        const tablesDir = resolveTablesDir(appwriteDir);
+
+        if (!fs.existsSync(collectionsDir)) {
+          MessageFormatter.error(`Collections directory not found: ${collectionsDir}`, undefined, { prefix: "Migration" });
+          return;
+        }
+
+        const collectionFiles = fs
+          .readdirSync(collectionsDir)
+          .filter(file => file.endsWith(".yaml") || file.endsWith(".yml"));
+
+        if (collectionFiles.length === 0) {
+          MessageFormatter.error("No YAML collection files found to migrate.", undefined, { prefix: "Migration" });
+          return;
+        }
+
+        const { confirmed } = await inquirer.prompt([
+          {
+            type: "confirm",
+            name: "confirmed",
+            message: `Proceed with migration? This will process ${collectionFiles.length} file(s).`,
+            default: false
+          }
+        ]);
+
+        if (!confirmed) {
+          MessageFormatter.info("Migration cancelled by user", { prefix: "Migration" });
+          return;
+        }
+
+        const yamlLoader = new YamlLoader(appwriteDir);
+        const result = await yamlLoader.migrateTerminology(
+          path.relative(appwriteDir, collectionsDir),
+          path.relative(appwriteDir, tablesDir),
+          true
+        );
+
+        if (result.errors.length > 0) {
+          MessageFormatter.warning(`Migration completed with ${result.errors.length} error(s).`, { prefix: "Migration" });
+        }
+
+        if (strategy === "move") {
+          const backupDir = `${collectionsDir}.backup.${Date.now()}`;
+          fs.renameSync(collectionsDir, backupDir);
+          MessageFormatter.info(`Collections moved to ${path.basename(backupDir)}`, { prefix: "Migration" });
+        }
+
+        MessageFormatter.success(`Collections migrated to tables (${result.migrated} converted, ${result.skipped} skipped).`, { prefix: "Migration" });
+        return;
+      }
+
       // Map user-friendly strategy names to internal MigrationStrategy types
       const migrationStrategy = strategy === "move" ? "full_migration" :
                                strategy === "copy" || strategy === "dual" ? "dual_format" : "full_migration";
@@ -122,7 +184,9 @@ export const configCommands = {
 
       if (confirmed) {
         const result = executeMigrationPlan((cli as any).controller.config, plan);
-        await saveMigrationResult(result, (cli as any).currentDir);
+        const configDir = findAppwriteConfig(currentDir) || currentDir;
+        const outputPath = path.join(configDir, "appwriteConfig.ts");
+        await saveMigrationResult(result, outputPath, { originalConfigPath: outputPath });
 
         MessageFormatter.success("Collections to tables migration completed!", { prefix: "Migration" });
       } else {

package/src/cli/commands/databaseCommands.ts

@@ -1,14 +1,16 @@
 import inquirer from "inquirer";
 import chalk from "chalk";
 import { join } from "node:path";
-import { MessageFormatter } from "../../shared/messageFormatter.js";
+import { Query } from "node-appwrite";
+import { MessageFormatter } from '@njdamstra/appwrite-utils-helpers';
 import { ConfirmationDialogs } from "../../shared/confirmationDialogs.js";
 import { SelectionDialogs } from "../../shared/selectionDialogs.js";
 import type { DatabaseSelection, BucketSelection } from "../../shared/selectionDialogs.js";
-import { logger } from "../../shared/logging.js";
+import { logger } from '@njdamstra/appwrite-utils-helpers';
 import { fetchAllDatabases } from "../../databases/methods.js";
 import { listBuckets } from "../../storage/methods.js";
 import { getFunction, downloadLatestFunctionDeployment } from "../../functions/methods.js";
+import { wipeTableRows } from "../../collections/wipeOperations.js";
 import type { InteractiveCLI } from "../../interactiveCLI.js";
 
 export const databaseCommands = {
@@ -19,18 +21,40 @@ export const databaseCommands = {
       // Initialize controller
       await (cli as any).controller!.init();
 
-      // Get available and configured databases
-      const availableDatabases = await fetchAllDatabases((cli as any).controller!.database!);
+      // Get available databases from server and configured databases from local config
+      const serverDatabases = await fetchAllDatabases((cli as any).controller!.database!);
       const configuredDatabases = (cli as any).controller!.config?.databases || [];
 
+      // For PUSH operations: Merge local configured databases with server databases
+      // This allows pushing databases that don't exist on the server yet
+      const serverDbIds = new Set(serverDatabases.map(db => db.$id));
+      const mergedDatabases = [...serverDatabases];
+
+      // Add locally configured databases that don't exist on server yet
+      for (const configDb of configuredDatabases) {
+        const dbId = configDb.$id;
+        if (dbId && !serverDbIds.has(dbId)) {
+          // Create a pseudo-database object for selection
+          mergedDatabases.push({
+            $id: dbId,
+            name: configDb.name || dbId,
+            $createdAt: new Date().toISOString(),
+            $updatedAt: new Date().toISOString(),
+            enabled: true,
+            _isLocalOnly: true, // Mark as not yet on server
+          } as any);
+          MessageFormatter.info(`Including local database "${configDb.name || dbId}" (not yet on server)`, { prefix: "Database" });
+        }
+      }
+
       // Get local collections for selection
       const localCollections = (cli as any).getLocalCollections();
 
       // Push operations always use local configuration as source of truth
 
-      // Select databases
+      // Select databases (now includes locally configured databases that don't exist on server)
       const selectedDatabaseIds = await SelectionDialogs.selectDatabases(
-        availableDatabases,
+        mergedDatabases,
         configuredDatabases,
         { showSelectAll: false, allowNewOnly: false, defaultSelected: [] }
       );
@@ -45,7 +69,7 @@ export const databaseCommands = {
       const availableTablesMap = new Map<string, any[]>();
 
       for (const databaseId of selectedDatabaseIds) {
-        const database = availableDatabases.find(db => db.$id === databaseId)!;
+        const database = mergedDatabases.find(db => db.$id === databaseId)!;
 
         // Use the existing selectCollectionsAndTables method
         const selectedCollections = await (cli as any).selectCollectionsAndTables(
@@ -106,7 +130,7 @@ export const databaseCommands = {
                 selectedBucketIds,
                 availableBuckets,
                 configuredBuckets,
-                availableDatabases
+                mergedDatabases
               );
 
               MessageFormatter.info(`Selected ${bucketSelections.length} storage bucket(s)`, { prefix: "Database" });
@@ -121,7 +145,7 @@ export const databaseCommands = {
       // Create DatabaseSelection objects
       const databaseSelections = SelectionDialogs.createDatabaseSelection(
         selectedDatabaseIds,
-        availableDatabases,
+        mergedDatabases,
         tableSelectionsMap,
         configuredDatabases,
         availableTablesMap
@@ -745,5 +769,133 @@ export const databaseCommands = {
       }
     }
     MessageFormatter.success("Wipe collections operation completed", { prefix: "Wipe" });
+  },
+
+  async wipeTablesData(cli: InteractiveCLI): Promise<void> {
+    const controller = (cli as any).controller;
+
+    if (!controller?.adapter) {
+      throw new Error(
+        "Database adapter is not initialized. TablesDB operations require adapter support."
+      );
+    }
+
+    try {
+      // Step 1: Select database (single selection for clearer UX)
+      const databases = await fetchAllDatabases(controller.database);
+
+      if (!databases || databases.length === 0) {
+        MessageFormatter.warning("No databases found", { prefix: "Wipe" });
+        return;
+      }
+
+      const { selectedDatabase } = await inquirer.prompt([
+        {
+          type: "list",
+          name: "selectedDatabase",
+          message: "Select database containing tables to wipe:",
+          choices: databases.map((db: any) => ({
+            name: `${db.name} (${db.$id})`,
+            value: db
+          }))
+        }
+      ]);
+
+      const database = selectedDatabase;
+
+      // Step 2: Get available tables
+      const adapter = controller.adapter;
+      const tablesResponse = await adapter.listTables({
+        databaseId: database.$id,
+        queries: [Query.limit(500)]
+      });
+      const availableTables = (tablesResponse as any).tables || [];
+
+      if (availableTables.length === 0) {
+        MessageFormatter.warning(`No tables found in database: ${database.name}`, { prefix: "Wipe" });
+        return;
+      }
+
+      // Step 3: Select tables using existing SelectionDialogs
+      const selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
+        database.$id,
+        database.name,
+        availableTables,
+        [], // No configured tables context needed for wipe
+        {
+          showSelectAll: true,
+          allowNewOnly: false,
+          defaultSelected: []
+        }
+      );
+
+      if (selectedTableIds.length === 0) {
+        MessageFormatter.warning("No tables selected. Operation cancelled.", { prefix: "Wipe" });
+        return;
+      }
+
+      // Step 4: Show confirmation with table details
+      const selectedTables = availableTables.filter((t: any) =>
+        selectedTableIds.includes(t.$id)
+      );
+      const tableNames = selectedTables.map((t: any) => t.name);
+
+      console.log(chalk.yellow.bold("\n⚠️  WARNING: Table Row Wipe Operation"));
+      console.log(chalk.yellow("This will delete ALL ROWS from the selected tables."));
+      console.log(chalk.yellow("The table structures will remain intact.\n"));
+      console.log(chalk.cyan("Database:"), chalk.white(database.name));
+      console.log(chalk.cyan("Tables to wipe:"));
+      tableNames.forEach((name: string) => console.log(chalk.white(`  • ${name}`)));
+      console.log();
+
+      const { confirmed } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "confirmed",
+          message: chalk.red.bold("Are you ABSOLUTELY SURE you want to wipe these table rows?"),
+          default: false
+        }
+      ]);
+
+      if (!confirmed) {
+        MessageFormatter.info("Wipe operation cancelled by user", { prefix: "Wipe" });
+        return;
+      }
+
+      // Step 5: Execute wipe using existing wipeTableRows function
+      MessageFormatter.progress("Starting table row wipe operation...", { prefix: "Wipe" });
+
+      for (const table of selectedTables) {
+        try {
+          MessageFormatter.info(`Wiping rows from table: ${table.name}`, { prefix: "Wipe" });
+
+          // Use existing wipeTableRows from wipeOperations.ts
+          await wipeTableRows(adapter, database.$id, table.$id);
+
+          MessageFormatter.success(
+            `Successfully wiped rows from table: ${table.name}`,
+            { prefix: "Wipe" }
+          );
+        } catch (error) {
+          MessageFormatter.error(
+            `Failed to wipe table ${table.name}`,
+            error instanceof Error ? error : new Error(String(error)),
+            { prefix: "Wipe" }
+          );
+        }
+      }
+
+      MessageFormatter.success(
+        `Wipe operation completed for ${selectedTables.length} table(s)`,
+        { prefix: "Wipe" }
+      );
+    } catch (error) {
+      MessageFormatter.error(
+        "Table wipe operation failed",
+        error instanceof Error ? error : new Error(String(error)),
+        { prefix: "Wipe" }
+      );
+      throw error;
+    }
   }
 };

package/src/cli/commands/functionCommands.ts

@@ -5,7 +5,7 @@ import os from "node:os";
 import { ulid } from "ulidx";
 import chalk from "chalk";
 import { Query } from "node-appwrite";
-import { MessageFormatter } from "../../shared/messageFormatter.js";
+import { MessageFormatter } from '@njdamstra/appwrite-utils-helpers';
 import {
   createFunctionTemplate,
   deleteFunction,
@@ -15,7 +15,7 @@ import {
 } from "../../functions/methods.js";
 import { deployLocalFunction } from "../../functions/deployments.js";
 import { discoverFnConfigs, mergeDiscoveredFunctions } from "../../functions/fnConfigDiscovery.js";
-import { addFunctionToYamlConfig, findYamlConfig } from "../../config/yamlConfig.js";
+import { addFunctionToYamlConfig, findYamlConfig } from "@njdamstra/appwrite-utils-helpers";
 import { RuntimeSchema, type AppwriteFunction, type Runtime, type Specification } from "@njdamstra/appwrite-utils";
 import type { InteractiveCLI } from "../../interactiveCLI.js";
 
@@ -326,7 +326,8 @@ export const functionCommands = {
             ...effectiveConfig,
             dirPath: functionPath,
           },
-          functionPath
+          functionPath,
+          yamlBaseDir
         );
         MessageFormatter.success("Function deployed successfully!", { prefix: "Functions" });
       } catch (error) {