@njdamstra/appwrite-utils-cli 1.10.1 → 1.11.0

package/dist/migrations/migrateStringsTypes.d.ts

@@ -0,0 +1,195 @@
+import { z } from "zod";
+export declare const MigrationTargetType: z.ZodEnum<{
+    varchar: "varchar";
+    text: "text";
+    mediumtext: "mediumtext";
+    longtext: "longtext";
+}>;
+export type MigrationTargetType = z.infer<typeof MigrationTargetType>;
+export declare const MigrationAction: z.ZodEnum<{
+    skip: "skip";
+    migrate: "migrate";
+}>;
+export type MigrationAction = z.infer<typeof MigrationAction>;
+export declare const MigrationPlanEntrySchema: z.ZodObject<{
+    databaseId: z.ZodString;
+    databaseName: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    attributeKey: z.ZodString;
+    currentType: z.ZodDefault<z.ZodString>;
+    currentSize: z.ZodNumber;
+    isRequired: z.ZodDefault<z.ZodBoolean>;
+    isArray: z.ZodDefault<z.ZodBoolean>;
+    isEncrypted: z.ZodDefault<z.ZodBoolean>;
+    hasDefault: z.ZodDefault<z.ZodBoolean>;
+    defaultValue: z.ZodOptional<z.ZodAny>;
+    suggestedType: z.ZodEnum<{
+        varchar: "varchar";
+        text: "text";
+        mediumtext: "mediumtext";
+        longtext: "longtext";
+    }>;
+    targetType: z.ZodEnum<{
+        varchar: "varchar";
+        text: "text";
+        mediumtext: "mediumtext";
+        longtext: "longtext";
+    }>;
+    targetSize: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodEnum<{
+        skip: "skip";
+        migrate: "migrate";
+    }>;
+    skipReason: z.ZodOptional<z.ZodString>;
+    indexesAffected: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type MigrationPlanEntry = z.infer<typeof MigrationPlanEntrySchema>;
+export declare const MigrationPlanSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    generatedAt: z.ZodString;
+    appwriteEndpoint: z.ZodOptional<z.ZodString>;
+    appwriteProject: z.ZodOptional<z.ZodString>;
+    summary: z.ZodObject<{
+        totalStringAttributes: z.ZodNumber;
+        toMigrate: z.ZodNumber;
+        toSkip: z.ZodNumber;
+        databaseCount: z.ZodNumber;
+        collectionCount: z.ZodNumber;
+    }, z.core.$strip>;
+    entries: z.ZodArray<z.ZodObject<{
+        databaseId: z.ZodString;
+        databaseName: z.ZodString;
+        collectionId: z.ZodString;
+        collectionName: z.ZodString;
+        attributeKey: z.ZodString;
+        currentType: z.ZodDefault<z.ZodString>;
+        currentSize: z.ZodNumber;
+        isRequired: z.ZodDefault<z.ZodBoolean>;
+        isArray: z.ZodDefault<z.ZodBoolean>;
+        isEncrypted: z.ZodDefault<z.ZodBoolean>;
+        hasDefault: z.ZodDefault<z.ZodBoolean>;
+        defaultValue: z.ZodOptional<z.ZodAny>;
+        suggestedType: z.ZodEnum<{
+            varchar: "varchar";
+            text: "text";
+            mediumtext: "mediumtext";
+            longtext: "longtext";
+        }>;
+        targetType: z.ZodEnum<{
+            varchar: "varchar";
+            text: "text";
+            mediumtext: "mediumtext";
+            longtext: "longtext";
+        }>;
+        targetSize: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodEnum<{
+            skip: "skip";
+            migrate: "migrate";
+        }>;
+        skipReason: z.ZodOptional<z.ZodString>;
+        indexesAffected: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
+export declare const CheckpointPhase: z.ZodEnum<{
+    pending: "pending";
+    completed: "completed";
+    failed: "failed";
+    backup_created: "backup_created";
+    data_copied_to_backup: "data_copied_to_backup";
+    data_verified_backup: "data_verified_backup";
+    original_deleted: "original_deleted";
+    new_attr_created: "new_attr_created";
+    data_copied_back: "data_copied_back";
+    data_verified_final: "data_verified_final";
+    backup_deleted: "backup_deleted";
+}>;
+export type CheckpointPhase = z.infer<typeof CheckpointPhase>;
+export declare const CheckpointEntrySchema: z.ZodObject<{
+    databaseId: z.ZodString;
+    collectionId: z.ZodString;
+    attributeKey: z.ZodString;
+    backupKey: z.ZodString;
+    phase: z.ZodEnum<{
+        pending: "pending";
+        completed: "completed";
+        failed: "failed";
+        backup_created: "backup_created";
+        data_copied_to_backup: "data_copied_to_backup";
+        data_verified_backup: "data_verified_backup";
+        original_deleted: "original_deleted";
+        new_attr_created: "new_attr_created";
+        data_copied_back: "data_copied_back";
+        data_verified_final: "data_verified_final";
+        backup_deleted: "backup_deleted";
+    }>;
+    targetType: z.ZodEnum<{
+        varchar: "varchar";
+        text: "text";
+        mediumtext: "mediumtext";
+        longtext: "longtext";
+    }>;
+    targetSize: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+    storedIndexes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodString;
+        attributes: z.ZodArray<z.ZodString>;
+        orders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CheckpointEntry = z.infer<typeof CheckpointEntrySchema>;
+export declare const MigrationCheckpointSchema: z.ZodObject<{
+    planFile: z.ZodString;
+    startedAt: z.ZodString;
+    lastUpdatedAt: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        databaseId: z.ZodString;
+        collectionId: z.ZodString;
+        attributeKey: z.ZodString;
+        backupKey: z.ZodString;
+        phase: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            failed: "failed";
+            backup_created: "backup_created";
+            data_copied_to_backup: "data_copied_to_backup";
+            data_verified_backup: "data_verified_backup";
+            original_deleted: "original_deleted";
+            new_attr_created: "new_attr_created";
+            data_copied_back: "data_copied_back";
+            data_verified_final: "data_verified_final";
+            backup_deleted: "backup_deleted";
+        }>;
+        targetType: z.ZodEnum<{
+            varchar: "varchar";
+            text: "text";
+            mediumtext: "mediumtext";
+            longtext: "longtext";
+        }>;
+        targetSize: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodString>;
+        storedIndexes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            type: z.ZodString;
+            attributes: z.ZodArray<z.ZodString>;
+            orders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MigrationCheckpoint = z.infer<typeof MigrationCheckpointSchema>;
+export interface AnalyzeOptions {
+    outputPath?: string;
+    verbose?: boolean;
+}
+export interface ExecuteOptions {
+    planPath: string;
+    keepBackups?: boolean;
+    dryRun?: boolean;
+    batchSize?: number;
+    batchDelayMs?: number;
+    checkpointPath?: string;
+}
+export declare function suggestTargetType(size: number, hasIndex: boolean): MigrationTargetType;
+export declare function generateBackupKey(originalKey: string): string;

package/dist/migrations/migrateStringsTypes.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+// ── Target types for string attribute migration ──
+export const MigrationTargetType = z.enum([
+    "varchar",
+    "text",
+    "mediumtext",
+    "longtext",
+]);
+export const MigrationAction = z.enum(["migrate", "skip"]);
+// ── Plan entry: one per attribute to migrate ──
+export const MigrationPlanEntrySchema = z.object({
+    databaseId: z.string(),
+    databaseName: z.string(),
+    collectionId: z.string(),
+    collectionName: z.string(),
+    attributeKey: z.string(),
+    currentType: z.string().default("string"),
+    currentSize: z.number(),
+    isRequired: z.boolean().default(false),
+    isArray: z.boolean().default(false),
+    isEncrypted: z.boolean().default(false),
+    hasDefault: z.boolean().default(false),
+    defaultValue: z.any().optional(),
+    suggestedType: MigrationTargetType,
+    targetType: MigrationTargetType,
+    targetSize: z.number().optional(), // varchar only
+    action: MigrationAction,
+    skipReason: z.string().optional(),
+    indexesAffected: z.array(z.string()).default([]),
+});
+// ── Plan: full migration plan (user-editable YAML) ──
+export const MigrationPlanSchema = z.object({
+    version: z.number().default(1),
+    generatedAt: z.string(),
+    appwriteEndpoint: z.string().optional(),
+    appwriteProject: z.string().optional(),
+    summary: z.object({
+        totalStringAttributes: z.number(),
+        toMigrate: z.number(),
+        toSkip: z.number(),
+        databaseCount: z.number(),
+        collectionCount: z.number(),
+    }),
+    entries: z.array(MigrationPlanEntrySchema),
+});
+// ── Checkpoint: tracks progress during execution ──
+export const CheckpointPhase = z.enum([
+    "pending",
+    "backup_created",
+    "data_copied_to_backup",
+    "data_verified_backup",
+    "original_deleted",
+    "new_attr_created",
+    "data_copied_back",
+    "data_verified_final",
+    "backup_deleted",
+    "completed",
+    "failed",
+]);
+export const CheckpointEntrySchema = z.object({
+    databaseId: z.string(),
+    collectionId: z.string(),
+    attributeKey: z.string(),
+    backupKey: z.string(),
+    phase: CheckpointPhase,
+    targetType: MigrationTargetType,
+    targetSize: z.number().optional(),
+    error: z.string().optional(),
+    // Store index definitions for recreation after attribute delete
+    storedIndexes: z
+        .array(z.object({
+        key: z.string(),
+        type: z.string(),
+        attributes: z.array(z.string()),
+        orders: z.array(z.string()).optional(),
+    }))
+        .default([]),
+});
+export const MigrationCheckpointSchema = z.object({
+    planFile: z.string(),
+    startedAt: z.string(),
+    lastUpdatedAt: z.string(),
+    entries: z.array(CheckpointEntrySchema),
+});
+// ── Helper: suggest target type from size + index presence ──
+export function suggestTargetType(size, hasIndex) {
+    // varchar supports up to 16,383 bytes and allows full indexing
+    if (size <= 768)
+        return "varchar";
+    if (hasIndex)
+        return "varchar"; // indexes require varchar
+    if (size <= 16_383)
+        return "text";
+    if (size <= 4_000_000)
+        return "mediumtext";
+    return "longtext";
+}
+// ── Helper: generate backup key with length limits ──
+const MAX_KEY_LENGTH = 36;
+const BACKUP_PREFIX = "_mig_";
+export function generateBackupKey(originalKey) {
+    const candidate = `${BACKUP_PREFIX}${originalKey}`;
+    if (candidate.length <= MAX_KEY_LENGTH) {
+        return candidate;
+    }
+    // Truncate + 4-char hash for uniqueness
+    const hash = simpleHash(originalKey);
+    const maxOrigLen = MAX_KEY_LENGTH - BACKUP_PREFIX.length - 1 - 4; // _mig_ + _ + hash4
+    return `_m_${originalKey.slice(0, maxOrigLen)}_${hash}`;
+}
+function simpleHash(str) {
+    let h = 0;
+    for (let i = 0; i < str.length; i++) {
+        h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h).toString(36).slice(0, 4).padStart(4, "0");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.10.1",
+  "version": "1.11.0",
   "main": "dist/main.js",
   "type": "module",
   "repository": {

package/src/cli/commands/migrateCommands.ts

@@ -0,0 +1,157 @@
+import inquirer from "inquirer";
+import path from "node:path";
+import { MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
+import type { InteractiveCLI } from "../../interactiveCLI.js";
+import {
+  analyzeStringAttributes,
+  executeMigrationPlan,
+} from "../../migrations/migrateStrings.js";
+import type { AnalyzeOptions, ExecuteOptions } from "../../migrations/migrateStringsTypes.js";
+
+export const migrateCommands = {
+  async migrateStrings(cli: InteractiveCLI): Promise<void> {
+    const { phase } = await inquirer.prompt([
+      {
+        type: "list",
+        name: "phase",
+        message: "String attribute migration:",
+        choices: [
+          {
+            name: "Analyze — scan local configs, generate migration plan (YAML)",
+            value: "analyze",
+          },
+          {
+            name: "Execute — run a migration plan against Appwrite server",
+            value: "execute",
+          },
+          { name: "Back", value: "back" },
+        ],
+      },
+    ]);
+
+    if (phase === "back") return;
+    if (phase === "analyze") {
+      await migrateCommands.analyzePhase(cli);
+    } else {
+      await migrateCommands.executePhase(cli);
+    }
+  },
+
+  async analyzePhase(cli: InteractiveCLI): Promise<void> {
+    const controller = (cli as any).controller;
+    if (!controller?.config) {
+      MessageFormatter.error(
+        "No configuration loaded. Make sure you have a valid .appwrite config.",
+        undefined,
+        { prefix: "Analyze" }
+      );
+      return;
+    }
+
+    const config = controller.config;
+    const collections = [
+      ...(config.collections || []),
+      ...(config.tables || []),
+    ];
+
+    if (collections.length === 0) {
+      MessageFormatter.warning(
+        "No collections/tables found in local config. Nothing to analyze.",
+        { prefix: "Analyze" }
+      );
+      return;
+    }
+
+    // Prompt for output path
+    const { outputPath } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "outputPath",
+        message: "Output path for migration plan:",
+        default: path.join(process.cwd(), "migrate-strings-plan.yaml"),
+      },
+    ]);
+
+    const options: AnalyzeOptions = { outputPath };
+
+    try {
+      analyzeStringAttributes(config, options);
+      MessageFormatter.success(
+        "Analysis complete. Review the YAML plan, edit targetType/action as needed, then run Execute.",
+        { prefix: "Analyze" }
+      );
+    } catch (err: any) {
+      MessageFormatter.error(
+        `Analysis failed: ${err.message}`,
+        undefined,
+        { prefix: "Analyze" }
+      );
+    }
+  },
+
+  async executePhase(cli: InteractiveCLI): Promise<void> {
+    const controller = (cli as any).controller;
+    if (!controller?.adapter) {
+      MessageFormatter.error(
+        "No database adapter available. Ensure a server connection is established.",
+        undefined,
+        { prefix: "Execute" }
+      );
+      return;
+    }
+
+    // Prompt for plan path
+    const { planPath } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "planPath",
+        message: "Path to migration plan YAML:",
+        default: path.join(process.cwd(), "migrate-strings-plan.yaml"),
+      },
+    ]);
+
+    const { keepBackups } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "keepBackups",
+        message: "Keep backup attributes after migration? (safer, uses more attribute slots)",
+        default: true,
+      },
+    ]);
+
+    const { dryRun } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "dryRun",
+        message: "Dry run? (no actual changes)",
+        default: false,
+      },
+    ]);
+
+    const options: ExecuteOptions = {
+      planPath,
+      keepBackups,
+      dryRun,
+    };
+
+    try {
+      const results = await executeMigrationPlan(controller.adapter, options);
+      if (results.failed > 0) {
+        MessageFormatter.warning(
+          `Migration completed with ${results.failed} failure(s). Check checkpoint file to resume.`,
+          { prefix: "Execute" }
+        );
+      } else {
+        MessageFormatter.success("Migration completed successfully.", {
+          prefix: "Execute",
+        });
+      }
+    } catch (err: any) {
+      MessageFormatter.error(
+        `Execution failed: ${err.message}`,
+        undefined,
+        { prefix: "Execute" }
+      );
+    }
+  },
+};

package/src/interactiveCLI.ts

@@ -46,6 +46,7 @@ import { storageCommands } from "./cli/commands/storageCommands.js";
 import { transferCommands } from "./cli/commands/transferCommands.js";
 import { schemaCommands } from "./cli/commands/schemaCommands.js";
 import { importFileCommands } from "./cli/commands/importFileCommands.js";
+import { migrateCommands } from "./cli/commands/migrateCommands.js";
 
 enum CHOICES {
   MIGRATE_CONFIG = "🔄 Migrate TypeScript config to YAML (.appwrite structure)",
@@ -71,6 +72,7 @@ enum CHOICES {
   RELOAD_CONFIG = "🔄 Reload configuration files",
   UPDATE_FUNCTION_SPEC = "⚙️ Update function specifications",
   MANAGE_BUCKETS = "🪣 Manage storage buckets",
+  MIGRATE_STRINGS = "🔄 Migrate string attributes to varchar/text types",
   EXIT = "👋 Exit",
 }
 
@@ -203,6 +205,10 @@ export class InteractiveCLI {
         case CHOICES.MANAGE_BUCKETS:
           await this.manageBuckets();
           break;
+        case CHOICES.MIGRATE_STRINGS:
+          await this.initControllerIfNeeded();
+          await migrateCommands.migrateStrings(this);
+          break;
         case CHOICES.EXIT:
           MessageFormatter.success("Goodbye!");
           process.exit(0);

package/src/main.ts

@@ -82,6 +82,12 @@ interface CliOptions {
   importFile?: string;
   targetDb?: string;
   targetTable?: string;
+  // String attribute migration
+  migrateStringsAnalyze?: boolean;
+  migrateStringsExecute?: string;
+  migrateStringsOutput?: string;
+  migrateStringsKeepBackups?: boolean;
+  migrateStringsDryRun?: boolean;
 }
 
 type ParsedArgv = ArgumentsCamelCase<CliOptions>;
@@ -621,6 +627,32 @@ const argv = yargs(hideBin(process.argv))
     type: "string",
     description: "Target table ID for --importFile (prompted if omitted)",
   })
+  .option("migrateStringsAnalyze", {
+    alias: ["migrate-strings-analyze"],
+    type: "boolean",
+    description: "Analyze local configs and generate a string-to-varchar/text migration plan (YAML)",
+  })
+  .option("migrateStringsExecute", {
+    alias: ["migrate-strings-execute"],
+    type: "string",
+    description: "Execute a string migration plan from the given YAML path",
+  })
+  .option("migrateStringsOutput", {
+    alias: ["migrate-strings-output"],
+    type: "string",
+    description: "Output path for the migration plan (default: ./migrate-strings-plan.yaml)",
+  })
+  .option("migrateStringsKeepBackups", {
+    alias: ["migrate-strings-keep-backups"],
+    type: "boolean",
+    default: true,
+    description: "Keep backup attributes after migration (default: true)",
+  })
+  .option("migrateStringsDryRun", {
+    alias: ["migrate-strings-dry-run"],
+    type: "boolean",
+    description: "Dry run — show what would happen without making changes",
+  })
   .parse() as ParsedArgv;
 
 async function main() {
@@ -842,6 +874,43 @@ async function main() {
       return;
     }
 
+    // String attribute migration (analyze or execute)
+    if (argv.migrateStringsAnalyze || argv.migrateStringsExecute) {
+      const { analyzeStringAttributes, executeMigrationPlan } = await import(
+        "./migrations/migrateStrings.js"
+      );
+
+      if (argv.migrateStringsAnalyze) {
+        if (!controller.config) {
+          MessageFormatter.error("No Appwrite configuration found", undefined, {
+            prefix: "Migration",
+          });
+          return;
+        }
+        analyzeStringAttributes(controller.config, {
+          outputPath: argv.migrateStringsOutput,
+        });
+      } else if (argv.migrateStringsExecute) {
+        if (!controller.adapter) {
+          MessageFormatter.error(
+            "No database adapter available. Ensure config has valid credentials.",
+            undefined,
+            { prefix: "Migration" }
+          );
+          return;
+        }
+        const results = await executeMigrationPlan(controller.adapter, {
+          planPath: argv.migrateStringsExecute,
+          keepBackups: argv.migrateStringsKeepBackups ?? true,
+          dryRun: argv.migrateStringsDryRun ?? false,
+        });
+        if (results.failed > 0) {
+          process.exit(1);
+        }
+      }
+      return;
+    }
+
     // List backups if requested
     if (parsedArgv.listBackups) {
       const { AdapterFactory } = await import("@njdamstra/appwrite-utils-helpers");