appwrite-utils-cli 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# appwrite-utils-cli
+
+## Overview
+
+`appwrite-utils-cli` is a powerful command-line interface tool designed for Appwrite developers who need to manage database migrations, schema generation, data import, and much more. This CLI tool facilitates complex tasks like setting up databases, running migrations, generating schemas, and managing backups efficiently, making it an indispensable part of your Appwrite project management.
+
+## Features
+
+- **Easy Configuration**: Initialize your Appwrite project configurations and setup directly from the command line.
+- **Database Migrations**: Control the migration process with options to target production, staging, or development environments.
+- **Schema Generation**: Generate and manage TypeScript schemas directly from your Appwrite database schemas.
+- **Data Import**: Facilitate the import of data into your Appwrite databases with comprehensive command-line support.
+- **Backup Management**: Create backups of your Appwrite databases to ensure data integrity and safety.
+- **Flexible Database Management**: Includes commands to wipe databases, documents, or user data, providing flexibility in managing your database state during development or testing.
+
+## Installation
+
+To use `appwrite-utils-cli`, you should install it globally via npm to make it accessible from anywhere in your command line:
+
+```bash
+npm install -g appwrite-utils-cli
+```
+
+## Usage
+
+After installation, you can access the tool directly from your command line using the provided commands. Here's how you can use the different functionalities:
+
+### Initialization
+
+Set up your Appwrite project with necessary configurations:
+
+```bash
+appwrite-setup
+```
+
+To generate an example configuration file:
+
+```bash
+appwrite-setup --example
+```
+
+### Running Migrations and Tasks
+
+Run migration and management tasks with specific flags according to your needs:
+
+```bash
+appwrite-migrate --args
+```
+
+Replace `--args` with the appropriate options:
+
+- `--prod`: Run tasks in the production environment.
+- `--staging`: Run tasks in the staging environment.
+- `--dev`: Run tasks in the development environment.
+- `--wipe`: Wipe all databases.
+- `--wipe-docs` or `--wipeDocs`: Wipe all documents in the databases.
+- `--generate`: Generate TypeScript schemas from database schemas.
+- `--import`: Import data into your databases.
+- `--backup`: Perform a backup of your databases.
+- `--wipe-users` or `--wipeUsers`: Wipe all user data.
+
+For example, to run migrations in a development environment and import data:
+
+```bash
+appwrite-migrate --dev --import
+```
+
+To initialize your project, generate schemas, but not import data:
+
+```bash
+appwrite-migrate --init
+```
+
+This setup ensures that developers have robust tools at their fingertips to manage complex Appwrite projects effectively from the command line. I also have added logging automatically for information and errors as the console can be hard to keep up with.
+
+### Roadmap
+
+- Syncing configuration
+- Better file format for config (potentially)
+- Separation of collections and import configuration from main config

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { UtilsController } from "./utilsController.js";
+const args = process.argv.slice(2);
+async function main() {
+    const controller = new UtilsController();
+    await controller.init();
+    let runProd = false;
+    let runStaging = false;
+    let runDev = false;
+    let doBackup = false;
+    let wipeDatabases = false;
+    let wipeUsers = false;
+    let generateSchemas = false;
+    let importData = false;
+    let wipeDocuments = false;
+    if (args.includes("--prod")) {
+        runProd = true;
+    }
+    if (args.includes("--staging")) {
+        runStaging = true;
+    }
+    if (args.includes("--dev")) {
+        runDev = true;
+    }
+    if (args.includes("--wipe")) {
+        wipeDatabases = true;
+    }
+    if (args.includes("--wipe-docs") || args.includes("--wipeDocs")) {
+        wipeDocuments = true;
+    }
+    if (args.includes("--generate")) {
+        generateSchemas = true;
+    }
+    if (args.includes("--import")) {
+        importData = true;
+    }
+    if (args.includes("--backup")) {
+        doBackup = true;
+    }
+    if (args.includes("--wipe-users") || args.includes("--wipeUsers")) {
+        wipeUsers = true;
+    }
+    if (args.includes("--init")) {
+        await controller.run({
+            runProd: runProd,
+            runStaging: runStaging,
+            runDev: runDev,
+            doBackup: doBackup,
+            wipeDatabases: wipeDatabases,
+            wipeUsers: wipeUsers,
+            wipeDocumentStorage: wipeDocuments,
+            generateSchemas: true,
+            generateMockData: false,
+            importData: false,
+            checkDuplicates: false,
+        });
+    }
+    else {
+        await controller.run({
+            runProd: runProd,
+            runStaging: runStaging,
+            runDev: runDev,
+            doBackup: doBackup,
+            wipeDatabases: wipeDatabases,
+            wipeDocumentStorage: wipeDocuments,
+            generateSchemas: generateSchemas,
+            generateMockData: false,
+            wipeUsers: wipeUsers,
+            importData: importData,
+            checkDuplicates: false,
+        });
+    }
+}
+main().catch(console.error);

package/dist/migrations/afterImportActions.d.ts

@@ -0,0 +1,12 @@
+import { type Models } from "node-appwrite";
+import type { AppwriteConfig } from "./schema.js";
+export interface AfterImportActions {
+    [key: string]: (config: AppwriteConfig, ...args: any[]) => Promise<any>;
+}
+export declare const afterImportActions: {
+    updateCreatedDocument: (config: AppwriteConfig, dbId: string, collId: string, docId: string, data: any) => Promise<void>;
+    checkAndUpdateFieldInDocument: (config: AppwriteConfig, dbId: string, collId: string, docId: string, fieldName: string, oldFieldValue: any, newFieldValue: any) => Promise<void>;
+    setFieldFromOtherCollectionDocument: (config: AppwriteConfig, dbId: string, collIdOrName: string, docId: string, fieldName: string, otherCollIdOrName: string, otherDocId: string, otherFieldName: string) => Promise<void>;
+    createOrGetBucket: (config: AppwriteConfig, bucketName: string, bucketId?: string, permissions?: string[], fileSecurity?: boolean, enabled?: boolean, maxFileSize?: number, allowedExtensions?: string[], compression?: string, encryption?: boolean, antivirus?: boolean) => Promise<Models.Bucket | undefined>;
+    createFileAndUpdateField: (config: AppwriteConfig, dbId: string, collId: string, docId: string, fieldName: string, bucketId: string, filePath: string, fileName: string) => Promise<void>;
+};

package/dist/migrations/afterImportActions.js

@@ -0,0 +1,196 @@
+import { Databases, Storage, InputFile, Query, ID, Client, } from "node-appwrite";
+import path from "path";
+import fs from "fs";
+import os from "os";
+const getDatabaseFromConfig = (config) => {
+    if (!config.appwriteClient) {
+        config.appwriteClient = new Client()
+            .setEndpoint(config.appwriteEndpoint)
+            .setProject(config.appwriteProject)
+            .setKey(config.appwriteKey);
+    }
+    return new Databases(config.appwriteClient);
+};
+const getStorageFromConfig = (config) => {
+    if (!config.appwriteClient) {
+        config.appwriteClient = new Client()
+            .setEndpoint(config.appwriteEndpoint)
+            .setProject(config.appwriteProject)
+            .setKey(config.appwriteKey);
+    }
+    return new Storage(config.appwriteClient);
+};
+export const afterImportActions = {
+    updateCreatedDocument: async (config, dbId, collId, docId, data) => {
+        try {
+            const db = getDatabaseFromConfig(config);
+            await db.updateDocument(dbId, collId, docId, data);
+        }
+        catch (error) {
+            console.error("Error updating document: ", error);
+        }
+    },
+    checkAndUpdateFieldInDocument: async (config, dbId, collId, docId, fieldName, oldFieldValue, newFieldValue) => {
+        try {
+            const db = getDatabaseFromConfig(config);
+            const doc = await db.getDocument(dbId, collId, docId);
+            if (doc[fieldName] == oldFieldValue) {
+                await db.updateDocument(dbId, collId, docId, {
+                    [fieldName]: newFieldValue,
+                });
+            }
+        }
+        catch (error) {
+            console.error("Error updating document: ", error);
+        }
+    },
+    setFieldFromOtherCollectionDocument: async (config, dbId, collIdOrName, docId, fieldName, otherCollIdOrName, otherDocId, otherFieldName) => {
+        const db = getDatabaseFromConfig(config);
+        // Helper function to find a collection ID by name or return the ID if given
+        const findCollectionId = async (collectionIdentifier) => {
+            const collectionsPulled = await db.listCollections(dbId, [
+                Query.limit(25),
+                Query.equal("name", collectionIdentifier),
+            ]);
+            if (collectionsPulled.total > 0) {
+                return collectionsPulled.collections[0].$id;
+            }
+            else {
+                // Assuming the passed identifier might directly be an ID if not found by name
+                return collectionIdentifier;
+            }
+        };
+        try {
+            // Resolve the IDs for both the target and other collections
+            const targetCollectionId = await findCollectionId(collIdOrName);
+            const otherCollectionId = await findCollectionId(otherCollIdOrName);
+            // Retrieve the "other" document
+            const otherDoc = await db.getDocument(dbId, otherCollectionId, otherDocId);
+            const valueToSet = otherDoc[otherFieldName];
+            if (valueToSet) {
+                // Update the target document
+                await db.updateDocument(dbId, targetCollectionId, docId, {
+                    [fieldName]: valueToSet,
+                });
+            }
+            console.log(`Field ${fieldName} updated successfully in document ${docId}.`);
+        }
+        catch (error) {
+            console.error("Error setting field from other collection document: ", error);
+        }
+    },
+    createOrGetBucket: async (config, bucketName, bucketId, permissions, fileSecurity, enabled, maxFileSize, allowedExtensions, compression, encryption, antivirus) => {
+        try {
+            const storage = getStorageFromConfig(config);
+            const bucket = await storage.listBuckets([
+                Query.equal("name", bucketName),
+            ]);
+            if (bucket.buckets.length > 0) {
+                return bucket.buckets[0];
+            }
+            else if (bucketId) {
+                try {
+                    return await storage.getBucket(bucketId);
+                }
+                catch (error) {
+                    return await storage.createBucket(bucketId, bucketName, permissions, fileSecurity, enabled, maxFileSize, allowedExtensions, compression, encryption, antivirus);
+                }
+            }
+            else {
+                return await storage.createBucket(bucketId || ID.unique(), bucketName, permissions, fileSecurity, enabled, maxFileSize, allowedExtensions, compression, encryption, antivirus);
+            }
+        }
+        catch (error) {
+            console.error("Error creating or getting bucket: ", error);
+        }
+    },
+    createFileAndUpdateField: async (config, dbId, collId, docId, fieldName, bucketId, filePath, fileName) => {
+        try {
+            const db = getDatabaseFromConfig(config);
+            const storage = getStorageFromConfig(config);
+            const collection = await db.getCollection(dbId, collId);
+            const attributes = collection.attributes;
+            const attribute = attributes.find((a) => a.key === fieldName);
+            // console.log(
+            //   `Processing field ${fieldName} in collection ${collId} for document ${docId} in database ${dbId} in bucket ${bucketId} with path ${filePath} and name ${fileName}...`
+            // );
+            let isArray = false;
+            if (!attribute) {
+                console.log(`Field ${fieldName} not found in collection ${collId}, weird, skipping...`);
+                return;
+            }
+            else if (attribute.array === true) {
+                isArray = true;
+            }
+            // Define a helper function to check if a value is a URL
+            const isUrl = (value) => typeof value === "string" &&
+                (value.startsWith("http://") || value.startsWith("https://"));
+            const doc = await db.getDocument(dbId, collId, docId);
+            const existingFieldValue = doc[fieldName];
+            // Handle the case where the field is an array
+            let updateData = isArray ? [] : "";
+            if (isArray && Array.isArray(existingFieldValue)) {
+                updateData = existingFieldValue.filter((val) => !isUrl(val)); // Remove URLs from the array
+            }
+            // Process file upload and update logic
+            if (isUrl(filePath)) {
+                // Create a temporary directory
+                const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "appwrite_tmp"));
+                const tempFilePath = path.join(tempDir, fileName);
+                // Download the file using fetch
+                const response = await fetch(filePath);
+                if (!response.ok)
+                    console.error(`Failed to fetch ${filePath}: ${response.statusText} for document ${docId} with field ${fieldName}`);
+                // Use arrayBuffer if buffer is not available
+                const arrayBuffer = await response.arrayBuffer();
+                const buffer = Buffer.from(arrayBuffer);
+                fs.writeFileSync(tempFilePath, buffer);
+                // Create InputFile from the downloaded file
+                const inputFile = InputFile.fromPath(tempFilePath, fileName);
+                // Use the full file name (with extension) for creating the file
+                const file = await storage.createFile(bucketId, ID.unique(), inputFile);
+                console.log("Created file from URL: ", file.$id);
+                // After uploading, adjust the updateData based on whether the field is an array or not
+                if (isArray) {
+                    updateData = [...updateData, file.$id]; // Append the new file ID
+                }
+                else {
+                    updateData = file.$id; // Set the new file ID
+                }
+                // console.log(
+                //   "Updating document with file: ",
+                //   doc.$id,
+                //   `${fieldName}: `,
+                //   updateData
+                // );
+                // If the file was downloaded, delete it after uploading
+                fs.unlinkSync(tempFilePath);
+            }
+            else {
+                const files = fs.readdirSync(filePath);
+                const fileFullName = files.find((file) => file.includes(fileName));
+                if (!fileFullName) {
+                    console.error(`File starting with '${fileName}' not found in '${filePath}'`);
+                    return;
+                }
+                const pathToFile = path.join(filePath, fileFullName);
+                const inputFile = InputFile.fromPath(pathToFile, fileName);
+                const file = await storage.createFile(bucketId, ID.unique(), inputFile);
+                if (isArray) {
+                    updateData = [...updateData, file.$id]; // Append the new file ID
+                }
+                else {
+                    updateData = file.$id; // Set the new file ID
+                }
+                await db.updateDocument(dbId, collId, doc.$id, {
+                    [fieldName]: updateData,
+                });
+                console.log("Created file from path: ", file.$id);
+            }
+        }
+        catch (error) {
+            console.error("Error creating file and updating field: ", error);
+            console.log(`Params were: dbId: ${dbId}, collId: ${collId}, docId: ${docId}, fieldName: ${fieldName}, filePath: ${filePath}, fileName: ${fileName}`);
+        }
+    },
+};

package/dist/migrations/attributes.d.ts

@@ -0,0 +1,4 @@
+import { type Databases, type Models } from "node-appwrite";
+import type { Attribute } from "./schema.js";
+export declare const createOrUpdateAttribute: (db: Databases, dbId: string, collection: Models.Collection, attribute: Attribute) => Promise<void>;
+export declare const createUpdateCollectionAttributes: (db: Databases, dbId: string, collection: Models.Collection, attributes: Attribute[]) => Promise<void>;

package/dist/migrations/attributes.js

@@ -0,0 +1,158 @@
+import { Query } from "node-appwrite";
+import { nameToIdMapping, enqueueOperation } from "./queue.js";
+export const createOrUpdateAttribute = async (db, dbId, collection, attribute) => {
+    let action = "create";
+    let foundAttribute;
+    try {
+        foundAttribute = await db.getAttribute(dbId, collection.$id, attribute.key);
+    }
+    catch (error) {
+        foundAttribute = undefined;
+    }
+    let numSameAttributes = 0;
+    if (foundAttribute && foundAttribute.key === attribute.key) {
+        numSameAttributes++;
+        return;
+    }
+    else if (foundAttribute) {
+        action = "update";
+    }
+    // Relationship attribute logic with adjustments
+    let collectionFoundViaRelatedCollection;
+    let relatedCollectionId;
+    if (attribute.type === "relationship") {
+        if (nameToIdMapping.has(attribute.relatedCollection)) {
+            relatedCollectionId = nameToIdMapping.get(attribute.relatedCollection);
+            try {
+                collectionFoundViaRelatedCollection = await db.getCollection(dbId, relatedCollectionId);
+            }
+            catch (e) {
+                console.log(`Collection not found: ${attribute.relatedCollection} when nameToIdMapping was set`);
+                collectionFoundViaRelatedCollection = undefined;
+            }
+        }
+        else {
+            const collectionsPulled = await db.listCollections(dbId, [
+                Query.equal("name", attribute.relatedCollection),
+            ]);
+            if (collectionsPulled.total > 0) {
+                collectionFoundViaRelatedCollection = collectionsPulled.collections[0];
+                relatedCollectionId = collectionFoundViaRelatedCollection.$id;
+                nameToIdMapping.set(attribute.relatedCollection, relatedCollectionId);
+            }
+        }
+        if (!(relatedCollectionId && collectionFoundViaRelatedCollection)) {
+            console.log(`Enqueueing operation for attribute: ${attribute.key}`);
+            enqueueOperation({
+                type: "attribute",
+                collectionId: collection.$id,
+                collection: collection,
+                attribute,
+                dependencies: [attribute.relatedCollection],
+            });
+            return;
+        }
+    }
+    switch (attribute.type) {
+        case "string":
+            if (action === "create") {
+                await db.createStringAttribute(dbId, collection.$id, attribute.key, attribute.size, attribute.required, attribute.xdefault || undefined, attribute.array, attribute.encrypted);
+            }
+            else {
+                await db.updateStringAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "integer":
+            if (action === "create") {
+                await db.createIntegerAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.min, attribute.max, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateIntegerAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.min || 0, attribute.max || 2147483647, attribute.xdefault || undefined);
+            }
+            break;
+        case "float":
+            if (action === "create") {
+                await db.createFloatAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.min, attribute.max, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateFloatAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.min || 0, attribute.max || 2147483647, attribute.xdefault || undefined);
+            }
+            break;
+        case "boolean":
+            if (action === "create") {
+                await db.createBooleanAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateBooleanAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "datetime":
+            if (action === "create") {
+                await db.createDatetimeAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateDatetimeAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "email":
+            if (action === "create") {
+                await db.createEmailAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateEmailAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "ip":
+            if (action === "create") {
+                await db.createIpAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateIpAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "url":
+            if (action === "create") {
+                await db.createUrlAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateUrlAttribute(dbId, collection.$id, attribute.key, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "enum":
+            if (action === "create") {
+                await db.createEnumAttribute(dbId, collection.$id, attribute.key, attribute.elements, attribute.required, attribute.xdefault || undefined, attribute.array);
+            }
+            else {
+                await db.updateEnumAttribute(dbId, collection.$id, attribute.key, attribute.elements, attribute.required, attribute.xdefault || undefined);
+            }
+            break;
+        case "relationship":
+            if (action === "create") {
+                await db.createRelationshipAttribute(dbId, collection.$id, relatedCollectionId, attribute.relationType, attribute.twoWay, attribute.key, attribute.twoWayKey, attribute.onDelete);
+            }
+            else {
+                await db.updateRelationshipAttribute(dbId, collection.$id, attribute.key, attribute.onDelete);
+            }
+            break;
+        default:
+            console.error("Invalid attribute type");
+            break;
+    }
+};
+export const createUpdateCollectionAttributes = async (db, dbId, collection, attributes) => {
+    console.log(`Creating/Updating attributes for collection: ${collection.name}`);
+    const batchSize = 3; // Size of each batch
+    for (let i = 0; i < attributes.length; i += batchSize) {
+        // Slice the attributes array to get a batch of at most batchSize elements
+        const batch = attributes.slice(i, i + batchSize);
+        const attributePromises = batch.map((attribute) => createOrUpdateAttribute(db, dbId, collection, attribute));
+        // Await the completion of all promises in the current batch
+        const results = await Promise.allSettled(attributePromises);
+        results.forEach((result) => {
+            if (result.status === "rejected") {
+                console.error("An attribute promise was rejected:", result.reason);
+            }
+        });
+    }
+    console.log(`Finished creating/updating attributes for collection: ${collection.name}`);
+};