@njdamstra/appwrite-utils-cli 1.11.1 → 1.11.3

package/dist/cli/commands/migrateCommands.js

@@ -1,5 +1,6 @@
 import inquirer from "inquirer";
 import path from "node:path";
+import fs from "node:fs";
 import { MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
 import { analyzeStringAttributes, executeMigrationPlan, } from "../../migrations/migrateStrings.js";
 export const migrateCommands = {
@@ -37,6 +38,30 @@ export const migrateCommands = {
             MessageFormatter.error("No database adapter available. Ensure a server connection is established.", undefined, { prefix: "Analyze" });
             return;
         }
+        // Prompt for database selection
+        const allDatabases = controller.config.databases || [];
+        let databaseIds;
+        if (allDatabases.length > 1) {
+            const { selectedDbs } = await inquirer.prompt([
+                {
+                    type: "checkbox",
+                    name: "selectedDbs",
+                    message: "Select databases to include in the analysis:",
+                    choices: allDatabases.map((db) => ({
+                        name: `${db.name} (${db.$id})`,
+                        value: db.$id,
+                        checked: true,
+                    })),
+                },
+            ]);
+            if (selectedDbs.length === 0) {
+                MessageFormatter.warning("No databases selected. Aborting.", { prefix: "Analyze" });
+                return;
+            }
+            if (selectedDbs.length < allDatabases.length) {
+                databaseIds = selectedDbs;
+            }
+        }
         // Prompt for output path
         const { outputPath } = await inquirer.prompt([
             {
@@ -46,7 +71,7 @@ export const migrateCommands = {
                 default: path.join(process.cwd(), "migrate-strings-plan.yaml"),
             },
         ]);
-        const options = { outputPath };
+        const options = { outputPath, databaseIds };
         try {
             await analyzeStringAttributes(controller.adapter, controller.config, options);
             MessageFormatter.success("Analysis complete. Review the YAML plan, edit targetType/action as needed, then run Execute.", { prefix: "Analyze" });
@@ -70,6 +95,27 @@ export const migrateCommands = {
                 default: path.join(process.cwd(), "migrate-strings-plan.yaml"),
             },
         ]);
+        // Check for existing checkpoint
+        let freshRun = false;
+        const checkpointPath = planPath.replace(/\.ya?ml$/, ".checkpoint.json");
+        if (fs.existsSync(checkpointPath)) {
+            const { cpAction } = await inquirer.prompt([
+                {
+                    type: "list",
+                    name: "cpAction",
+                    message: "Found an existing checkpoint from a previous run. What would you like to do?",
+                    choices: [
+                        { name: "Resume — continue from where it left off", value: "resume" },
+                        { name: "Start fresh — delete checkpoint and start over", value: "fresh" },
+                        { name: "Cancel", value: "cancel" },
+                    ],
+                },
+            ]);
+            if (cpAction === "cancel")
+                return;
+            if (cpAction === "fresh")
+                freshRun = true;
+        }
         const { keepBackups } = await inquirer.prompt([
             {
                 type: "confirm",
@@ -90,6 +136,7 @@ export const migrateCommands = {
             planPath,
             keepBackups,
             dryRun,
+            freshRun,
         };
         try {
             const results = await executeMigrationPlan(controller.adapter, options);

package/dist/main.js

@@ -469,6 +469,11 @@ const argv = yargs(hideBin(process.argv))
     alias: ["migrate-strings-output"],
     type: "string",
     description: "Output path for the migration plan (default: ./migrate-strings-plan.yaml)",
+})
+    .option("migrateStringsDbIds", {
+    alias: ["migrate-strings-db-ids"],
+    type: "string",
+    description: "Comma-separated database IDs to include in analysis (default: all)",
 })
     .option("migrateStringsKeepBackups", {
     alias: ["migrate-strings-keep-backups"],
@@ -480,6 +485,11 @@ const argv = yargs(hideBin(process.argv))
     alias: ["migrate-strings-dry-run"],
     type: "boolean",
     description: "Dry run — show what would happen without making changes",
+})
+    .option("migrateStringsFresh", {
+    alias: ["migrate-strings-fresh"],
+    type: "boolean",
+    description: "Ignore existing checkpoint and start migration fresh",
 })
     .parse();
 async function main() {
@@ -652,8 +662,12 @@ async function main() {
                     MessageFormatter.error("No database adapter available. Ensure config has valid credentials.", undefined, { prefix: "Migration" });
                     return;
                 }
+                const databaseIds = argv.migrateStringsDbIds
+                    ? argv.migrateStringsDbIds.split(",").map((s) => s.trim()).filter(Boolean)
+                    : undefined;
                 await analyzeStringAttributes(controller.adapter, controller.config, {
                     outputPath: argv.migrateStringsOutput,
+                    databaseIds,
                 });
             }
             else if (argv.migrateStringsExecute) {
@@ -665,6 +679,7 @@ async function main() {
                     planPath: argv.migrateStringsExecute,
                     keepBackups: argv.migrateStringsKeepBackups ?? true,
                     dryRun: argv.migrateStringsDryRun ?? false,
+                    freshRun: argv.migrateStringsFresh ?? false,
                 });
                 if (results.failed > 0) {
                     process.exit(1);

package/dist/migrations/migrateStrings.js

@@ -11,7 +11,11 @@ import { MigrationPlanSchema, MigrationCheckpointSchema, suggestTargetType, gene
 // Phase 1: Analyze — queries Appwrite server for real state
 // ────────────────────────────────────────────────────────
 export async function analyzeStringAttributes(adapter, config, options = {}) {
-    const databases = config.databases || [];
+    let databasesToScan = config.databases || [];
+    if (options.databaseIds?.length) {
+        databasesToScan = databasesToScan.filter(db => options.databaseIds.includes(db.$id));
+    }
+    const databases = databasesToScan;
     if (databases.length === 0) {
         MessageFormatter.warning("No databases configured. Nothing to analyze.", {
             prefix: "Analyze",
@@ -189,6 +193,12 @@ export async function executeMigrationPlan(adapter, options) {
     // Load or create checkpoint
     const checkpointPath = options.checkpointPath ||
         options.planPath.replace(/\.ya?ml$/, ".checkpoint.json");
+    if (options.freshRun && fs.existsSync(checkpointPath)) {
+        fs.unlinkSync(checkpointPath);
+        MessageFormatter.info("Deleted old checkpoint — starting fresh.", {
+            prefix: "Checkpoint",
+        });
+    }
     const checkpoint = loadOrCreateCheckpoint(checkpointPath, options.planPath);
     const batchSize = options.batchSize || 100;
     const batchDelayMs = options.batchDelayMs || 50;

package/dist/migrations/migrateStringsTypes.d.ts

@@ -182,6 +182,7 @@ export type MigrationCheckpoint = z.infer<typeof MigrationCheckpointSchema>;
 export interface AnalyzeOptions {
     outputPath?: string;
     verbose?: boolean;
+    databaseIds?: string[];
 }
 export interface ExecuteOptions {
     planPath: string;
@@ -190,6 +191,7 @@ export interface ExecuteOptions {
     batchSize?: number;
     batchDelayMs?: number;
     checkpointPath?: string;
+    freshRun?: boolean;
 }
 export declare function suggestTargetType(size: number, hasIndex: boolean): MigrationTargetType;
 export declare function generateBackupKey(originalKey: string): string;

package/dist/migrations/migrateStringsTypes.js

@@ -97,16 +97,17 @@ export function suggestTargetType(size, hasIndex) {
 }
 // ── Helper: generate backup key with length limits ──
 const MAX_KEY_LENGTH = 36;
-const BACKUP_PREFIX = "_mig_";
+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
+    // Truncate + 4-char hash for uniqueness: m_ + orig + _ + hash(4)
     const hash = simpleHash(originalKey);
-    const maxOrigLen = MAX_KEY_LENGTH - BACKUP_PREFIX.length - 1 - 4; // _mig_ + _ + hash4
-    return `_m_${originalKey.slice(0, maxOrigLen)}_${hash}`;
+    const TRUNC_PREFIX = "m_";
+    const maxOrigLen = MAX_KEY_LENGTH - TRUNC_PREFIX.length - 1 - 4;
+    return `${TRUNC_PREFIX}${originalKey.slice(0, maxOrigLen)}_${hash}`;
 }
 function simpleHash(str) {
     let h = 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.11.1",
+  "version": "1.11.3",
   "main": "dist/main.js",
   "type": "module",
   "repository": {

package/src/cli/commands/migrateCommands.ts

@@ -1,5 +1,6 @@
 import inquirer from "inquirer";
 import path from "node:path";
+import fs from "node:fs";
 import { MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
 import type { InteractiveCLI } from "../../interactiveCLI.js";
 import {
@@ -48,6 +49,31 @@ export const migrateCommands = {
       return;
     }
 
+    // Prompt for database selection
+    const allDatabases = controller.config.databases || [];
+    let databaseIds: string[] | undefined;
+    if (allDatabases.length > 1) {
+      const { selectedDbs } = await inquirer.prompt([
+        {
+          type: "checkbox",
+          name: "selectedDbs",
+          message: "Select databases to include in the analysis:",
+          choices: allDatabases.map((db: any) => ({
+            name: `${db.name} (${db.$id})`,
+            value: db.$id,
+            checked: true,
+          })),
+        },
+      ]);
+      if (selectedDbs.length === 0) {
+        MessageFormatter.warning("No databases selected. Aborting.", { prefix: "Analyze" });
+        return;
+      }
+      if (selectedDbs.length < allDatabases.length) {
+        databaseIds = selectedDbs;
+      }
+    }
+
     // Prompt for output path
     const { outputPath } = await inquirer.prompt([
       {
@@ -58,7 +84,7 @@ export const migrateCommands = {
       },
     ]);
 
-    const options: AnalyzeOptions = { outputPath };
+    const options: AnalyzeOptions = { outputPath, databaseIds };
 
     try {
       await analyzeStringAttributes(controller.adapter, controller.config, options);
@@ -96,6 +122,26 @@ export const migrateCommands = {
       },
     ]);
 
+    // Check for existing checkpoint
+    let freshRun = false;
+    const checkpointPath = planPath.replace(/\.ya?ml$/, ".checkpoint.json");
+    if (fs.existsSync(checkpointPath)) {
+      const { cpAction } = await inquirer.prompt([
+        {
+          type: "list",
+          name: "cpAction",
+          message: "Found an existing checkpoint from a previous run. What would you like to do?",
+          choices: [
+            { name: "Resume — continue from where it left off", value: "resume" },
+            { name: "Start fresh — delete checkpoint and start over", value: "fresh" },
+            { name: "Cancel", value: "cancel" },
+          ],
+        },
+      ]);
+      if (cpAction === "cancel") return;
+      if (cpAction === "fresh") freshRun = true;
+    }
+
     const { keepBackups } = await inquirer.prompt([
       {
         type: "confirm",
@@ -118,6 +164,7 @@ export const migrateCommands = {
       planPath,
       keepBackups,
       dryRun,
+      freshRun,
     };
 
     try {

package/src/main.ts

@@ -86,8 +86,10 @@ interface CliOptions {
   migrateStringsAnalyze?: boolean;
   migrateStringsExecute?: string;
   migrateStringsOutput?: string;
+  migrateStringsDbIds?: string;
   migrateStringsKeepBackups?: boolean;
   migrateStringsDryRun?: boolean;
+  migrateStringsFresh?: boolean;
 }
 
 type ParsedArgv = ArgumentsCamelCase<CliOptions>;
@@ -642,6 +644,11 @@ const argv = yargs(hideBin(process.argv))
     type: "string",
     description: "Output path for the migration plan (default: ./migrate-strings-plan.yaml)",
   })
+  .option("migrateStringsDbIds", {
+    alias: ["migrate-strings-db-ids"],
+    type: "string",
+    description: "Comma-separated database IDs to include in analysis (default: all)",
+  })
   .option("migrateStringsKeepBackups", {
     alias: ["migrate-strings-keep-backups"],
     type: "boolean",
@@ -653,6 +660,11 @@ const argv = yargs(hideBin(process.argv))
     type: "boolean",
     description: "Dry run — show what would happen without making changes",
   })
+  .option("migrateStringsFresh", {
+    alias: ["migrate-strings-fresh"],
+    type: "boolean",
+    description: "Ignore existing checkpoint and start migration fresh",
+  })
   .parse() as ParsedArgv;
 
 async function main() {
@@ -889,8 +901,12 @@ async function main() {
           );
           return;
         }
+        const databaseIds = argv.migrateStringsDbIds
+          ? argv.migrateStringsDbIds.split(",").map((s: string) => s.trim()).filter(Boolean)
+          : undefined;
         await analyzeStringAttributes(controller.adapter, controller.config, {
           outputPath: argv.migrateStringsOutput,
+          databaseIds,
         });
       } else if (argv.migrateStringsExecute) {
         if (!controller.adapter) {
@@ -905,6 +921,7 @@ async function main() {
           planPath: argv.migrateStringsExecute,
           keepBackups: argv.migrateStringsKeepBackups ?? true,
           dryRun: argv.migrateStringsDryRun ?? false,
+          freshRun: argv.migrateStringsFresh ?? false,
         });
         if (results.failed > 0) {
           process.exit(1);

package/src/migrations/migrateStrings.ts

@@ -34,7 +34,11 @@ export async function analyzeStringAttributes(
   config: AppwriteConfig,
   options: AnalyzeOptions = {}
 ): Promise<MigrationPlan> {
-  const databases = config.databases || [];
+  let databasesToScan = config.databases || [];
+  if (options.databaseIds?.length) {
+    databasesToScan = databasesToScan.filter(db => options.databaseIds!.includes(db.$id));
+  }
+  const databases = databasesToScan;
   if (databases.length === 0) {
     MessageFormatter.warning("No databases configured. Nothing to analyze.", {
       prefix: "Analyze",
@@ -260,6 +264,12 @@ export async function executeMigrationPlan(
   const checkpointPath =
     options.checkpointPath ||
     options.planPath.replace(/\.ya?ml$/, ".checkpoint.json");
+  if (options.freshRun && fs.existsSync(checkpointPath)) {
+    fs.unlinkSync(checkpointPath);
+    MessageFormatter.info("Deleted old checkpoint — starting fresh.", {
+      prefix: "Checkpoint",
+    });
+  }
   const checkpoint = loadOrCreateCheckpoint(checkpointPath, options.planPath);
 
   const batchSize = options.batchSize || 100;

package/src/migrations/migrateStringsTypes.ts

@@ -108,6 +108,7 @@ export type MigrationCheckpoint = z.infer<typeof MigrationCheckpointSchema>;
 export interface AnalyzeOptions {
   outputPath?: string;
   verbose?: boolean;
+  databaseIds?: string[];
 }
 
 export interface ExecuteOptions {
@@ -117,6 +118,7 @@ export interface ExecuteOptions {
   batchSize?: number;
   batchDelayMs?: number;
   checkpointPath?: string;
+  freshRun?: boolean;
 }
 
 // ── Helper: suggest target type from size + index presence ──
@@ -136,17 +138,18 @@ export function suggestTargetType(
 // ── Helper: generate backup key with length limits ──
 
 const MAX_KEY_LENGTH = 36;
-const BACKUP_PREFIX = "_mig_";
+const BACKUP_PREFIX = "mig_";
 
 export function generateBackupKey(originalKey: string): string {
   const candidate = `${BACKUP_PREFIX}${originalKey}`;
   if (candidate.length <= MAX_KEY_LENGTH) {
     return candidate;
   }
-  // Truncate + 4-char hash for uniqueness
+  // Truncate + 4-char hash for uniqueness: m_ + orig + _ + hash(4)
   const hash = simpleHash(originalKey);
-  const maxOrigLen = MAX_KEY_LENGTH - BACKUP_PREFIX.length - 1 - 4; // _mig_ + _ + hash4
-  return `_m_${originalKey.slice(0, maxOrigLen)}_${hash}`;
+  const TRUNC_PREFIX = "m_";
+  const maxOrigLen = MAX_KEY_LENGTH - TRUNC_PREFIX.length - 1 - 4;
+  return `${TRUNC_PREFIX}${originalKey.slice(0, maxOrigLen)}_${hash}`;
 }
 
 function simpleHash(str: string): string {