appwrite-utils-cli 1.7.7 → 1.7.9

package/SELECTION_DIALOGS.md

@@ -0,0 +1,146 @@
+# Selection Dialogs System
+
+## Overview
+
+The `SelectionDialogs` class provides a comprehensive interactive selection system for the enhanced sync flow in the Appwrite Utils CLI. It enables users to select databases, tables/collections, and storage buckets with visual indicators for configured vs new items.
+
+## Features
+
+- **Visual Indicators**: ✅ for configured items, ○ for new items
+- **Multi-Selection Support**: Checkbox-style selection with "Select All" functionality
+- **Configuration Awareness**: Detects and highlights existing configurations
+- **Grouped Display**: Organizes buckets by database for better context
+- **Comprehensive Confirmation**: Shows detailed summary before sync execution
+- **Graceful Error Handling**: Proper error messages and cancellation support
+- **Type Safety**: Full TypeScript support with proper interfaces
+
+## Main Functions
+
+### `promptForExistingConfig(configuredItems: any[])`
+Prompts user about existing configuration with options to:
+- Sync existing configured items
+- Add/remove items from configuration
+
+### `selectDatabases(availableDatabases, configuredDatabases, options?)`
+Interactive database selection with:
+- Visual indicators for configured vs new databases
+- "Select All" functionality
+- Filtering options (new only, default selections)
+
+### `selectTablesForDatabase(databaseId, databaseName, availableTables, configuredTables, options?)`
+Table/collection selection for a specific database with:
+- Database context display
+- Table selection with indicators
+- Multi-selection support
+
+### `selectBucketsForDatabases(selectedDatabaseIds, availableBuckets, configuredBuckets, options?)`
+Storage bucket selection with:
+- Grouping by database
+- Relevance filtering (only buckets for selected databases)
+- Ungrouped/general storage support
+
+### `confirmSyncSelection(selectionSummary: SyncSelectionSummary)`
+Final confirmation dialog showing:
+- Complete selection summary
+- Statistics (total, new, existing items)
+- Detailed breakdown by category
+
+## Usage Example
+
+```typescript
+import { SelectionDialogs } from './shared/selectionDialogs.js';
+import type { Models } from 'node-appwrite';
+
+// 1. Check for existing configuration
+const { syncExisting, modifyConfiguration } = await SelectionDialogs.promptForExistingConfig(configuredDatabases);
+
+if (modifyConfiguration) {
+  // 2. Select databases
+  const selectedDatabaseIds = await SelectionDialogs.selectDatabases(
+    availableDatabases,
+    configuredDatabases,
+    { showSelectAll: true }
+  );
+
+  // 3. Select tables for each database
+  const tableSelectionsMap = new Map<string, string[]>();
+  for (const databaseId of selectedDatabaseIds) {
+    const selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
+      databaseId,
+      databaseName,
+      availableTables,
+      configuredTables
+    );
+    tableSelectionsMap.set(databaseId, selectedTableIds);
+  }
+
+  // 4. Select buckets
+  const selectedBucketIds = await SelectionDialogs.selectBucketsForDatabases(
+    selectedDatabaseIds,
+    availableBuckets,
+    configuredBuckets
+  );
+
+  // 5. Create selection summary and confirm
+  const selectionSummary = SelectionDialogs.createSyncSelectionSummary(
+    databaseSelections,
+    bucketSelections
+  );
+
+  const confirmed = await SelectionDialogs.confirmSyncSelection(selectionSummary);
+
+  if (confirmed) {
+    // Proceed with sync operation
+  }
+}
+```
+
+## Configuration Options
+
+### Database Selection Options
+- `showSelectAll`: Show "Select All" option (default: true)
+- `allowNewOnly`: Only show new/unconfigured databases (default: false)
+- `defaultSelected`: Array of database IDs to pre-select
+
+### Table Selection Options
+- `showSelectAll`: Show "Select All" option (default: true)
+- `allowNewOnly`: Only show new/unconfigured tables (default: false)
+- `defaultSelected`: Array of table IDs to pre-select
+- `showDatabaseContext`: Show database name in header (default: true)
+
+### Bucket Selection Options
+- `showSelectAll`: Show "Select All" option (default: true)
+- `allowNewOnly`: Only show new/unconfigured buckets (default: false)
+- `defaultSelected`: Array of bucket IDs to pre-select
+- `groupByDatabase`: Group buckets by database (default: true)
+
+## Interfaces
+
+### `SyncSelectionSummary`
+Contains complete selection information:
+- `databases`: Array of selected databases with their tables
+- `buckets`: Array of selected buckets
+- `totalDatabases/Tables/Buckets`: Count of selected items
+- `newItems/existingItems`: Breakdown of new vs existing configurations
+
+### `DatabaseSelection`
+Represents a selected database:
+- `databaseId/databaseName`: Database identification
+- `tableIds/tableNames`: Selected tables for this database
+- `isNew`: Whether this is a new configuration
+
+### `BucketSelection`
+Represents a selected bucket:
+- `bucketId/bucketName`: Bucket identification
+- `databaseId/databaseName`: Associated database (if applicable)
+- `isNew`: Whether this is a new configuration
+
+## Integration
+
+The selection dialogs are designed to integrate seamlessly with the existing CLI infrastructure:
+
+- Uses `MessageFormatter` for consistent styling
+- Integrates with existing logging system
+- Follows established error handling patterns
+- Compatible with existing configuration management
+- Uses inquirer.js for interactive prompts

package/dist/cli/commands/databaseCommands.js

@@ -3,32 +3,94 @@ import chalk from "chalk";
 import { join } from "node:path";
 import { MessageFormatter } from "../../shared/messageFormatter.js";
 import { ConfirmationDialogs } from "../../shared/confirmationDialogs.js";
+import { SelectionDialogs } from "../../shared/selectionDialogs.js";
+import { logger } from "../../shared/logging.js";
 import { fetchAllDatabases } from "../../databases/methods.js";
 import { listBuckets } from "../../storage/methods.js";
 import { getFunction, downloadLatestFunctionDeployment } from "../../functions/methods.js";
 export const databaseCommands = {
     async syncDb(cli) {
         MessageFormatter.progress("Pushing local configuration to Appwrite...", { prefix: "Database" });
-        const databases = await cli.selectDatabases(cli.getLocalDatabases(), chalk.blue("Select local databases to push:"), true);
-        if (!databases.length) {
-            MessageFormatter.warning("No databases selected. Skipping database sync.", { prefix: "Database" });
-            return;
-        }
         try {
-            // Loop through each database and prompt for collections specific to that database
-            for (const database of databases) {
-                MessageFormatter.info(`\n📦 Configuring push for database: ${database.name}`, { prefix: "Database" });
-                const collections = await cli.selectCollectionsAndTables(database, cli.controller.database, chalk.blue(`Select collections/tables to push to "${database.name}":`), true, // multiSelect
+            // Initialize controller
+            await cli.controller.init();
+            // Get available and configured databases
+            const availableDatabases = await fetchAllDatabases(cli.controller.database);
+            const configuredDatabases = cli.controller.config?.databases || [];
+            // Get local collections for selection
+            const localCollections = cli.getLocalCollections();
+            // Push operations always use local configuration as source of truth
+            // Select databases
+            const selectedDatabaseIds = await SelectionDialogs.selectDatabases(availableDatabases, configuredDatabases, { showSelectAll: true, allowNewOnly: false });
+            if (selectedDatabaseIds.length === 0) {
+                MessageFormatter.warning("No databases selected. Skipping database sync.", { prefix: "Database" });
+                return;
+            }
+            // Select tables/collections for each database using the existing method
+            const tableSelectionsMap = new Map();
+            const availableTablesMap = new Map();
+            for (const databaseId of selectedDatabaseIds) {
+                const database = availableDatabases.find(db => db.$id === databaseId);
+                // Use the existing selectCollectionsAndTables method
+                const selectedCollections = await cli.selectCollectionsAndTables(database, cli.controller.database, chalk.blue(`Select collections/tables to push to "${database.name}":`), true, // multiSelect
                 true // prefer local
                 );
-                if (collections.length === 0) {
+                // Map selected collections to table IDs
+                const selectedTableIds = selectedCollections.map((c) => c.$id || c.id);
+                // Store selections
+                tableSelectionsMap.set(databaseId, selectedTableIds);
+                availableTablesMap.set(databaseId, selectedCollections);
+                if (selectedCollections.length === 0) {
                     MessageFormatter.warning(`No collections selected for database "${database.name}". Skipping.`, { prefix: "Database" });
                     continue;
                 }
-                // Push selected collections to this specific database
-                await cli.controller.syncDb([database], collections);
-                MessageFormatter.success(`Pushed ${collections.length} collection(s) to database "${database.name}"`, { prefix: "Database" });
             }
+            // Ask if user wants to select buckets
+            const { selectBuckets } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "selectBuckets",
+                    message: "Do you want to select storage buckets to sync as well?",
+                    default: false,
+                },
+            ]);
+            let bucketSelections = [];
+            if (selectBuckets) {
+                // Get available and configured buckets
+                try {
+                    const availableBucketsResponse = await listBuckets(cli.controller.storage);
+                    const availableBuckets = availableBucketsResponse.buckets || [];
+                    const configuredBuckets = cli.controller.config?.buckets || [];
+                    if (availableBuckets.length === 0) {
+                        MessageFormatter.warning("No storage buckets available in remote instance.", { prefix: "Database" });
+                    }
+                    else {
+                        // Select buckets using SelectionDialogs
+                        const selectedBucketIds = await SelectionDialogs.selectBucketsForDatabases(selectedDatabaseIds, availableBuckets, configuredBuckets, { showSelectAll: true, groupByDatabase: true });
+                        if (selectedBucketIds.length > 0) {
+                            // Create BucketSelection objects
+                            bucketSelections = SelectionDialogs.createBucketSelection(selectedBucketIds, availableBuckets, configuredBuckets, availableDatabases);
+                            MessageFormatter.info(`Selected ${bucketSelections.length} storage bucket(s)`, { prefix: "Database" });
+                        }
+                    }
+                }
+                catch (error) {
+                    MessageFormatter.warning("Failed to fetch storage buckets. Continuing with databases only.", { prefix: "Database" });
+                    logger.warn("Storage bucket fetch failed during syncDb", { error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            // Create DatabaseSelection objects
+            const databaseSelections = SelectionDialogs.createDatabaseSelection(selectedDatabaseIds, availableDatabases, tableSelectionsMap, configuredDatabases, availableTablesMap);
+            // Show confirmation summary
+            const selectionSummary = SelectionDialogs.createSyncSelectionSummary(databaseSelections, bucketSelections);
+            const confirmed = await SelectionDialogs.confirmSyncSelection(selectionSummary, 'push');
+            if (!confirmed) {
+                MessageFormatter.info("Push operation cancelled by user", { prefix: "Database" });
+                return;
+            }
+            // Perform selective push using the controller
+            MessageFormatter.progress("Starting selective push...", { prefix: "Database" });
+            await cli.controller.selectivePush(databaseSelections, bucketSelections);
             MessageFormatter.success("\n✅ All database configurations pushed successfully!", { prefix: "Database" });
             // Then handle functions if requested
             const { syncFunctions } = await inquirer.prompt([
@@ -73,19 +135,23 @@ export const databaseCommands = {
         ]);
         if (syncDatabases) {
             const remoteDatabases = await fetchAllDatabases(cli.controller.database);
-            // Use the controller's synchronizeConfigurations method which handles collections properly
-            MessageFormatter.progress("Pulling collections and generating collection files...", { prefix: "Collections" });
-            await cli.controller.synchronizeConfigurations(remoteDatabases);
-            // Also configure buckets for any new databases
+            // First, prepare the combined database list for bucket configuration
             const localDatabases = cli.controller.config?.databases || [];
-            const updatedConfig = await cli.configureBuckets({
+            const allDatabases = [
+                ...localDatabases,
+                ...remoteDatabases.filter((rd) => !localDatabases.some((ld) => ld.name === rd.name)),
+            ];
+            // Configure buckets FIRST to get user selections before writing config
+            MessageFormatter.progress("Configuring storage buckets...", { prefix: "Buckets" });
+            const configWithBuckets = await cli.configureBuckets({
                 ...cli.controller.config,
-                databases: [
-                    ...localDatabases,
-                    ...remoteDatabases.filter((rd) => !localDatabases.some((ld) => ld.name === rd.name)),
-                ],
+                databases: allDatabases,
             });
-            cli.controller.config = updatedConfig;
+            // Update controller config with bucket selections
+            cli.controller.config = configWithBuckets;
+            // Now synchronize configurations with the updated config that includes bucket selections
+            MessageFormatter.progress("Pulling collections and generating collection files...", { prefix: "Collections" });
+            await cli.controller.synchronizeConfigurations(remoteDatabases, configWithBuckets);
         }
         // Then sync functions
         const { syncFunctions } = await inquirer.prompt([

package/dist/config/services/ConfigLoaderService.d.ts

@@ -30,6 +30,13 @@ export interface CollectionLoadOptions {
  * - Validates and normalizes configuration data
  */
 export declare class ConfigLoaderService {
+    /**
+     * Normalizes function dirPath to absolute path
+     * @param func Function configuration object
+     * @param configDir Directory containing the config file
+     * @returns Function with normalized dirPath
+     */
+    private normalizeFunctionPath;
     /**
      * Loads configuration from a discovered path, auto-detecting the type
      * @param configPath Path to the configuration file

package/dist/config/services/ConfigLoaderService.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { resolve as resolvePath, dirname, isAbsolute } from "node:path";
 import yaml from "js-yaml";
 import { register } from "tsx/esm/api";
 import { pathToFileURL } from "node:url";
@@ -8,6 +9,7 @@ import { normalizeYamlData } from "../../utils/yamlConverter.js";
 import { loadYamlConfig } from "../yamlConfig.js";
 import { loadAppwriteProjectConfig, projectConfigToAppwriteConfig, getCollectionsFromProject } from "../../utils/projectConfig.js";
 import { loadYamlCollection, loadYamlTable, } from "../../utils/configDiscovery.js";
+import { expandTildePath } from "../../functions/pathResolution.js";
 /**
  * Service for loading and parsing Appwrite configuration files.
  *
@@ -25,6 +27,31 @@ import { loadYamlCollection, loadYamlTable, } from "../../utils/configDiscovery.
  * - Validates and normalizes configuration data
  */
 export class ConfigLoaderService {
+    /**
+     * Normalizes function dirPath to absolute path
+     * @param func Function configuration object
+     * @param configDir Directory containing the config file
+     * @returns Function with normalized dirPath
+     */
+    normalizeFunctionPath(func, configDir) {
+        if (!func.dirPath) {
+            return func;
+        }
+        // Expand tilde first
+        const expandedPath = expandTildePath(func.dirPath);
+        // If already absolute, return as-is
+        if (isAbsolute(expandedPath)) {
+            return {
+                ...func,
+                dirPath: expandedPath
+            };
+        }
+        // Resolve relative to config directory
+        return {
+            ...func,
+            dirPath: resolvePath(configDir, expandedPath)
+        };
+    }
     /**
      * Loads configuration from a discovered path, auto-detecting the type
      * @param configPath Path to the configuration file
@@ -46,6 +73,11 @@ export class ConfigLoaderService {
             if (!partialConfig.appwriteEndpoint || !partialConfig.appwriteProject) {
                 throw new Error("JSON project config must contain at minimum 'endpoint' and 'projectId' fields");
             }
+            const configDir = path.dirname(configPath);
+            // Normalize function paths
+            const normalizedFunctions = partialConfig.functions
+                ? partialConfig.functions.map(func => this.normalizeFunctionPath(func, configDir))
+                : [];
             return {
                 appwriteEndpoint: partialConfig.appwriteEndpoint,
                 appwriteProject: partialConfig.appwriteProject,
@@ -73,7 +105,7 @@ export class ConfigLoaderService {
                 },
                 databases: partialConfig.databases || [],
                 buckets: partialConfig.buckets || [],
-                functions: partialConfig.functions || [],
+                functions: normalizedFunctions,
                 collections: partialConfig.collections || [],
                 sessionCookie: partialConfig.sessionCookie,
                 authMethod: partialConfig.authMethod || "auto",
@@ -114,6 +146,10 @@ export class ConfigLoaderService {
             }
             // Load collections and tables from their respective directories
             const configDir = path.dirname(yamlPath);
+            // Normalize function paths
+            if (config.functions) {
+                config.functions = config.functions.map(func => this.normalizeFunctionPath(func, configDir));
+            }
             const collectionsDir = path.join(configDir, config.schemaConfig?.collectionsDirectory || "collections");
             const tablesDir = path.join(configDir, config.schemaConfig?.tablesDirectory || "tables");
             // Detect API mode to determine priority order
@@ -175,6 +211,11 @@ export class ConfigLoaderService {
             if (!config) {
                 throw new Error(`Failed to load TypeScript config from: ${tsPath}`);
             }
+            // Normalize function paths
+            const configDir = path.dirname(tsPath);
+            if (config.functions) {
+                config.functions = config.functions.map(func => this.normalizeFunctionPath(func, configDir));
+            }
             MessageFormatter.success(`Loaded TypeScript config from: ${tsPath}`, {
                 prefix: "Config",
             });
@@ -210,6 +251,11 @@ export class ConfigLoaderService {
             if (collections.length > 0) {
                 appwriteConfig.collections = collections;
             }
+            // Normalize function paths
+            const configDir = path.dirname(jsonPath);
+            if (appwriteConfig.functions) {
+                appwriteConfig.functions = appwriteConfig.functions.map(func => this.normalizeFunctionPath(func, configDir));
+            }
             MessageFormatter.success(`Loaded project config from: ${jsonPath}`, {
                 prefix: "Config",
             });

package/dist/functions/deployments.js

@@ -11,23 +11,7 @@ import { execSync } from "child_process";
 import { createFunction, getFunction, updateFunction, updateFunctionSpecifications, } from "./methods.js";
 import ignore from "ignore";
 import { MessageFormatter } from "../shared/messageFormatter.js";
-const findFunctionDirectory = (basePath, functionName) => {
-    const normalizedName = functionName.toLowerCase().replace(/\s+/g, "-");
-    const dirs = fs.readdirSync(basePath, { withFileTypes: true });
-    for (const dir of dirs) {
-        if (dir.isDirectory()) {
-            const fullPath = join(basePath, dir.name);
-            if (dir.name.toLowerCase() === normalizedName) {
-                return fullPath;
-            }
-            const nestedResult = findFunctionDirectory(fullPath, functionName);
-            if (nestedResult) {
-                return nestedResult;
-            }
-        }
-    }
-    return undefined;
-};
+import { resolveFunctionDirectory, validateFunctionDirectory } from './pathResolution.js';
 export const deployFunction = async (client, functionId, codePath, activate = true, entrypoint = "index.js", commands = "npm install", ignored = [
     "node_modules",
     ".git",
@@ -123,12 +107,10 @@ export const deployLocalFunction = async (client, functionName, functionConfig,
     catch (error) {
         functionExists = false;
     }
-    const resolvedPath = functionPath ||
-        functionConfig.dirPath ||
-        findFunctionDirectory(process.cwd(), functionName) ||
-        join(process.cwd(), "functions", functionName.toLowerCase().replace(/\s+/g, "-"));
-    if (!fs.existsSync(resolvedPath)) {
-        throw new Error(`Function directory not found at ${resolvedPath}`);
+    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" });

package/dist/functions/methods.js

@@ -6,6 +6,7 @@ import {} from "appwrite-utils";
 import chalk from "chalk";
 import { extract as extractTar } from "tar";
 import { MessageFormatter } from "../shared/messageFormatter.js";
+import { expandTildePath, normalizeFunctionName } from "./pathResolution.js";
 /**
  * Validates and filters events array for Appwrite functions
  * - Filters out empty/invalid strings
@@ -41,7 +42,7 @@ export const downloadLatestFunctionDeployment = async (client, functionId, baseP
     const latestDeployment = functionDeployments.deployments[0];
     const deploymentData = await functions.getDeploymentDownload(functionId, latestDeployment.$id);
     // Create function directory using provided basePath
-    const functionDir = join(basePath, functionInfo.name.toLowerCase().replace(/\s+/g, "-"));
+    const functionDir = join(basePath, normalizeFunctionName(functionInfo.name));
     await fs.promises.mkdir(functionDir, { recursive: true });
     // Create temporary file for tar extraction
     const tarPath = join(functionDir, "temp.tar.gz");
@@ -119,7 +120,8 @@ export const updateFunction = async (client, functionConfig) => {
     return functionResponse;
 };
 export const createFunctionTemplate = async (templateType, functionName, basePath = "./functions") => {
-    const functionPath = join(basePath, functionName);
+    const expandedBasePath = expandTildePath(basePath);
+    const functionPath = join(expandedBasePath, functionName);
     const currentFileUrl = import.meta.url;
     const currentDir = dirname(fileURLToPath(currentFileUrl));
     const templatesPath = join(currentDir, "templates", templateType);

package/dist/functions/pathResolution.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Expands tilde (~) in paths to the user's home directory
+ * @param pathStr - Path string that may contain ~
+ * @returns Expanded path with home directory
+ */
+export declare function expandTildePath(pathStr: string): string;
+/**
+ * Normalizes function name to standard format (lowercase, dashes instead of spaces)
+ * @param name - Function name to normalize
+ * @returns Normalized function name
+ */
+export declare function normalizeFunctionName(name: string): string;
+/**
+ * Validates that a directory exists and contains function markers
+ * @param dirPath - Directory path to validate
+ * @returns True if directory is a valid function directory
+ */
+export declare function validateFunctionDirectory(dirPath: string): boolean;
+/**
+ * Helper function to search for function in standard locations
+ * @param configDirPath - Directory where config file is located
+ * @param normalizedName - Normalized function name
+ * @returns First valid function directory path or undefined
+ */
+export declare function findFunctionInStandardLocations(configDirPath: string, normalizedName: string): string | undefined;
+/**
+ * Resolves the absolute path to a function directory
+ * Handles multiple resolution strategies with proper priority
+ *
+ * @param functionName - Name of the function
+ * @param configDirPath - Directory where config file is located
+ * @param dirPath - Optional explicit dirPath from config
+ * @param explicitPath - Optional path passed as parameter (highest priority)
+ * @returns Absolute path to the function directory
+ * @throws Error if function directory cannot be found or is invalid
+ */
+export declare function resolveFunctionDirectory(functionName: string, configDirPath: string, dirPath?: string, explicitPath?: string): string;