@njdamstra/appwrite-utils-cli 1.8.9

package/dist/shared/attributeMapper.js

@@ -0,0 +1,203 @@
+function ensureNumber(n) {
+    if (n === null || n === undefined)
+        return undefined;
+    const num = Number(n);
+    return Number.isFinite(num) ? num : undefined;
+}
+/**
+ * Map a schema Attribute into DatabaseAdapter CreateAttributeParams
+ * Only includes fields valid for the specific type to satisfy TS unions.
+ * Also normalizes min/max ordering for numeric types to avoid server errors.
+ */
+export function mapToCreateAttributeParams(attr, base) {
+    const type = String(attr.type || "").toLowerCase();
+    const required = !!attr.required;
+    const array = !!attr.array;
+    const xdefault = attr.xdefault;
+    const encrypt = attr.encrypt;
+    // Numeric helpers
+    const rawMin = ensureNumber(attr.min);
+    const rawMax = ensureNumber(attr.max);
+    let min = rawMin;
+    let max = rawMax;
+    if (min !== undefined && max !== undefined && min >= max) {
+        // Swap to satisfy server-side validation
+        const tmp = min;
+        min = Math.min(min, max);
+        max = Math.max(tmp, max);
+        if (min === max) {
+            // If still equal, unset max to avoid error
+            max = undefined;
+        }
+    }
+    switch (type) {
+        case "string":
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                size: attr.size ?? 255,
+                required,
+                default: xdefault,
+                array,
+                encrypt: !!encrypt,
+            };
+        case "integer":
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                required,
+                default: xdefault,
+                array,
+                min,
+                max,
+            };
+        case "double":
+        case "float":
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                required,
+                default: xdefault,
+                array,
+                min,
+                max,
+            };
+        case "boolean":
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                required,
+                default: xdefault,
+                array,
+            };
+        case "datetime":
+        case "email":
+        case "ip":
+        case "url":
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                required,
+                default: xdefault,
+                array,
+            };
+        case "enum":
+            {
+                const elements = attr.elements;
+                if (!Array.isArray(elements) || elements.length === 0) {
+                    // Creating an enum without elements is invalid – fail fast with clear messaging
+                    throw new Error(`Enum attribute '${attr.key}' requires a non-empty 'elements' array for creation`);
+                }
+            }
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                required,
+                default: xdefault,
+                array,
+                elements: attr.elements,
+            };
+        case "relationship": {
+            // Relationship attributes require related collection and metadata
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                relatedCollection: attr.relatedCollection,
+                relationType: attr.relationType,
+                twoWay: attr.twoWay,
+                twoWayKey: attr.twoWayKey,
+                onDelete: attr.onDelete,
+                side: attr.side,
+            };
+        }
+        default:
+            return {
+                databaseId: base.databaseId,
+                tableId: base.tableId,
+                key: attr.key,
+                type,
+                required,
+            };
+    }
+}
+/**
+ * Map a schema Attribute into DatabaseAdapter UpdateAttributeParams
+ * Omits fields that are not explicitly provided, and guards enum updates
+ * so we never send an empty elements array (preserve existing on server).
+ */
+export function mapToUpdateAttributeParams(attr, base) {
+    const type = String(attr.type || "").toLowerCase();
+    const params = {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+    };
+    const setIfDefined = (key, value) => {
+        if (value !== undefined)
+            params[key] = value;
+    };
+    // Common fields
+    setIfDefined("type", type);
+    setIfDefined("required", attr.required);
+    // Only send default if explicitly provided and not on required
+    if (!attr.required && attr.xdefault !== undefined) {
+        setIfDefined("default", attr.xdefault);
+    }
+    setIfDefined("array", attr.array);
+    // encrypt only applies to string types
+    if (type === "string")
+        setIfDefined("encrypt", attr.encrypt);
+    // Numeric normalization
+    const toNum = (n) => (n === null || n === undefined ? undefined : (Number(n)));
+    let min = toNum(attr.min);
+    let max = toNum(attr.max);
+    if (min !== undefined && max !== undefined && min >= max) {
+        const tmp = min;
+        min = Math.min(min, max);
+        max = Math.max(tmp, max);
+        if (min === max)
+            max = undefined;
+    }
+    switch (type) {
+        case "string":
+            setIfDefined("size", attr.size);
+            break;
+        case "integer":
+        case "float":
+        case "double":
+            setIfDefined("min", min);
+            setIfDefined("max", max);
+            break;
+        case "enum": {
+            const elements = attr.elements;
+            if (Array.isArray(elements) && elements.length > 0) {
+                // Only include when non-empty; otherwise preserve existing on server
+                setIfDefined("elements", elements);
+            }
+            break;
+        }
+        case "relationship": {
+            setIfDefined("relatedCollection", attr.relatedCollection);
+            setIfDefined("relationType", attr.relationType);
+            setIfDefined("twoWay", attr.twoWay);
+            setIfDefined("twoWayKey", attr.twoWayKey);
+            setIfDefined("onDelete", attr.onDelete);
+            break;
+        }
+    }
+    return params;
+}

package/dist/shared/backupMetadataSchema.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+/**
+ * Schema for centralized backup tracking table (_appwrite_backups)
+ *
+ * Tracks all backups created for databases, buckets, and comprehensive backups
+ */
+export type BackupType = 'database' | 'bucket' | 'comprehensive';
+export type BackupFormat = 'json' | 'zip';
+export type BackupStatus = 'completed' | 'partial' | 'failed';
+export type RestorationStatus = 'completed' | 'partial' | 'failed' | 'not_restored';
+export declare const BACKUP_TYPES: readonly ["database", "bucket", "comprehensive"];
+export declare const BACKUP_FORMATS: readonly ["json", "zip"];
+export declare const BACKUP_STATUSES: readonly ["completed", "partial", "failed"];
+export declare const RESTORATION_STATUSES: readonly ["completed", "partial", "failed", "not_restored"];
+export declare const BackupTypeSchema: z.ZodEnum<{
+    bucket: "bucket";
+    database: "database";
+    comprehensive: "comprehensive";
+}>;
+export declare const BackupFormatSchema: z.ZodEnum<{
+    json: "json";
+    zip: "zip";
+}>;
+export declare const BackupStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    partial: "partial";
+}>;
+export declare const RestorationStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    partial: "partial";
+    not_restored: "not_restored";
+}>;
+export interface BackupMetadata {
+    $id: string;
+    $createdAt: string;
+    $updatedAt: string;
+    backupType: BackupType;
+    backupId: string;
+    manifestFileId?: string;
+    format: BackupFormat;
+    sizeBytes: number;
+    databaseId?: string;
+    bucketId?: string;
+    comprehensiveBackupId?: string;
+    collections?: number;
+    documents?: number;
+    fileCount?: number;
+    status: BackupStatus;
+    error?: string;
+    restoredAt?: string;
+    restorationStatus: RestorationStatus;
+    restorationError?: string;
+}
+export declare const BackupMetadataSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $createdAt: z.ZodString;
+    $updatedAt: z.ZodString;
+    backupType: z.ZodEnum<{
+        bucket: "bucket";
+        database: "database";
+        comprehensive: "comprehensive";
+    }>;
+    backupId: z.ZodString;
+    manifestFileId: z.ZodOptional<z.ZodString>;
+    format: z.ZodEnum<{
+        json: "json";
+        zip: "zip";
+    }>;
+    sizeBytes: z.ZodNumber;
+    databaseId: z.ZodOptional<z.ZodString>;
+    bucketId: z.ZodOptional<z.ZodString>;
+    comprehensiveBackupId: z.ZodOptional<z.ZodString>;
+    collections: z.ZodOptional<z.ZodNumber>;
+    documents: z.ZodOptional<z.ZodNumber>;
+    fileCount: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        partial: "partial";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+    restoredAt: z.ZodOptional<z.ZodString>;
+    restorationStatus: z.ZodDefault<z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        partial: "partial";
+        not_restored: "not_restored";
+    }>>;
+    restorationError: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const BACKUP_TABLE_ID = "appwrite_backups";
+export declare const BACKUP_TABLE_NAME = "Backup Tracking";

package/dist/shared/backupMetadataSchema.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export const BACKUP_TYPES = ['database', 'bucket', 'comprehensive'];
+export const BACKUP_FORMATS = ['json', 'zip'];
+export const BACKUP_STATUSES = ['completed', 'partial', 'failed'];
+export const RESTORATION_STATUSES = ['completed', 'partial', 'failed', 'not_restored'];
+export const BackupTypeSchema = z.enum(['database', 'bucket', 'comprehensive']);
+export const BackupFormatSchema = z.enum(['json', 'zip']);
+export const BackupStatusSchema = z.enum(['completed', 'partial', 'failed']);
+export const RestorationStatusSchema = z.enum(['completed', 'partial', 'failed', 'not_restored']);
+export const BackupMetadataSchema = z.object({
+    $id: z.string(),
+    $createdAt: z.string(),
+    $updatedAt: z.string(),
+    // Core backup info
+    backupType: BackupTypeSchema,
+    backupId: z.string(),
+    manifestFileId: z.string().optional(),
+    format: BackupFormatSchema,
+    sizeBytes: z.number(),
+    // Resource identification
+    databaseId: z.string().optional(),
+    bucketId: z.string().optional(),
+    comprehensiveBackupId: z.string().optional(),
+    // Database-specific metrics
+    collections: z.number().optional(),
+    documents: z.number().optional(),
+    // Bucket-specific metrics
+    fileCount: z.number().optional(),
+    // Status tracking
+    status: BackupStatusSchema,
+    error: z.string().optional(),
+    // Restoration tracking
+    restoredAt: z.string().optional(),
+    restorationStatus: RestorationStatusSchema.default('not_restored'),
+    restorationError: z.string().optional()
+});
+export const BACKUP_TABLE_ID = "appwrite_backups";
+export const BACKUP_TABLE_NAME = "Backup Tracking";

package/dist/shared/backupTracking.d.ts

@@ -0,0 +1,18 @@
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { type BackupMetadata } from "./backupMetadataSchema.js";
+/**
+ * Creates the backup tracking table in the specified database
+ */
+export declare function createBackupTrackingTable(db: DatabaseAdapter, databaseId: string): Promise<void>;
+/**
+ * Records backup metadata in the tracking table
+ */
+export declare function recordBackup(db: DatabaseAdapter, databaseId: string, metadata: Omit<BackupMetadata, '$id' | '$createdAt' | '$updatedAt'>): Promise<BackupMetadata>;
+/**
+ * Lists all backups for a database, sorted by creation date (newest first)
+ */
+export declare function listBackups(db: DatabaseAdapter, databaseId: string): Promise<BackupMetadata[]>;
+/**
+ * Gets the most recent backup for a database
+ */
+export declare function getLastBackup(db: DatabaseAdapter, databaseId: string): Promise<BackupMetadata | null>;

package/dist/shared/backupTracking.js

@@ -0,0 +1,176 @@
+import { logger } from "./logging.js";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import { BACKUP_TABLE_ID, BACKUP_TABLE_NAME, BackupMetadataSchema } from "./backupMetadataSchema.js";
+/**
+ * Checks if backup tracking table exists in database
+ */
+async function tableExists(db, databaseId) {
+    try {
+        await db.getTable({ databaseId, tableId: BACKUP_TABLE_ID });
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Creates the backup tracking table in the specified database
+ */
+export async function createBackupTrackingTable(db, databaseId) {
+    // Check if table already exists
+    const exists = await tableExists(db, databaseId);
+    if (exists) {
+        logger.debug("Backup tracking table already exists", {
+            databaseId,
+            tableId: BACKUP_TABLE_ID
+        });
+        return;
+    }
+    logger.info("Creating backup tracking table", {
+        databaseId,
+        tableId: BACKUP_TABLE_ID
+    });
+    // Create table
+    await tryAwaitWithRetry(async () => {
+        await db.createTable({
+            databaseId,
+            id: BACKUP_TABLE_ID,
+            name: BACKUP_TABLE_NAME
+        });
+    });
+    // Create attributes
+    const attributes = [
+        {
+            key: "backupId",
+            type: "string",
+            size: 50,
+            required: true
+        },
+        {
+            key: "databaseId",
+            type: "string",
+            size: 50,
+            required: true
+        },
+        {
+            key: "sizeBytes",
+            type: "integer",
+            required: true
+        },
+        {
+            key: "collections",
+            type: "integer",
+            required: true
+        },
+        {
+            key: "documents",
+            type: "integer",
+            required: true
+        },
+        {
+            key: "format",
+            type: "enum",
+            elements: ["json", "zip"],
+            required: true
+        },
+        {
+            key: "status",
+            type: "enum",
+            elements: ["completed", "failed"],
+            required: true
+        },
+        {
+            key: "error",
+            type: "string",
+            size: 10000,
+            required: false
+        }
+    ];
+    for (const attr of attributes) {
+        await tryAwaitWithRetry(async () => {
+            await db.createAttribute({
+                databaseId,
+                tableId: BACKUP_TABLE_ID,
+                ...attr
+            });
+        });
+    }
+    logger.info("Backup tracking table created successfully", {
+        databaseId,
+        tableId: BACKUP_TABLE_ID
+    });
+}
+/**
+ * Records backup metadata in the tracking table
+ */
+export async function recordBackup(db, databaseId, metadata) {
+    // Ensure tracking table exists
+    await createBackupTrackingTable(db, databaseId);
+    // Create backup record
+    const result = await db.createRow({
+        databaseId,
+        tableId: BACKUP_TABLE_ID,
+        id: ID.unique(),
+        data: {
+            backupId: metadata.backupId,
+            databaseId: metadata.databaseId,
+            sizeBytes: metadata.sizeBytes,
+            collections: metadata.collections,
+            documents: metadata.documents,
+            format: metadata.format,
+            status: metadata.status,
+            error: metadata.error
+        }
+    });
+    logger.info("Recorded backup metadata", {
+        backupId: metadata.backupId,
+        databaseId: metadata.databaseId,
+        format: metadata.format
+    });
+    return result.data;
+}
+/**
+ * Lists all backups for a database, sorted by creation date (newest first)
+ */
+export async function listBackups(db, databaseId) {
+    try {
+        const result = await db.listRows({
+            databaseId,
+            tableId: BACKUP_TABLE_ID,
+            queries: [
+                Query.orderDesc("$createdAt"),
+                Query.limit(100) // Limit to last 100 backups
+            ]
+        });
+        return (result.rows || []);
+    }
+    catch (error) {
+        // Table might not exist yet
+        logger.debug("No backup tracking table found", { databaseId });
+        return [];
+    }
+}
+/**
+ * Gets the most recent backup for a database
+ */
+export async function getLastBackup(db, databaseId) {
+    try {
+        const result = await db.listRows({
+            databaseId,
+            tableId: BACKUP_TABLE_ID,
+            queries: [
+                Query.orderDesc("$createdAt"),
+                Query.limit(1)
+            ]
+        });
+        if (result.rows && result.rows.length > 0) {
+            return result.rows[0];
+        }
+        return null;
+    }
+    catch (error) {
+        logger.debug("No backup found or table doesn't exist", { databaseId });
+        return null;
+    }
+}

package/dist/shared/confirmationDialogs.d.ts

@@ -0,0 +1,75 @@
+export interface DestructiveOperationOptions {
+    operation: string;
+    targets: string[];
+    consequences?: string[];
+    requireExplicitConfirmation?: boolean;
+    confirmationText?: string;
+    skipConfirmation?: boolean;
+}
+export interface BackupPromptOptions {
+    operation: string;
+    targets: string[];
+    recommendBackup?: boolean;
+    backupMessage?: string;
+}
+export declare class ConfirmationDialogs {
+    /**
+     * Shows a confirmation dialog for destructive operations
+     */
+    static confirmDestructiveOperation(options: DestructiveOperationOptions): Promise<boolean>;
+    /**
+     * Prompts user about creating a backup before a destructive operation
+     */
+    static promptForBackup(options: BackupPromptOptions): Promise<'yes' | 'no' | 'skip'>;
+    /**
+     * Shows a final confirmation before proceeding with an operation
+     */
+    static finalConfirmation(operation: string, details?: string[]): Promise<boolean>;
+    /**
+     * Specialized confirmation for database wiping
+     */
+    static confirmDatabaseWipe(databaseNames: string[], options?: {
+        includeStorage?: boolean;
+        includeUsers?: boolean;
+        skipConfirmation?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Specialized confirmation for collection wiping
+     */
+    static confirmCollectionWipe(databaseName: string, collectionNames: string[], options?: {
+        skipConfirmation?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Specialized confirmation for function deployment
+     */
+    static confirmFunctionDeployment(functionNames: string[], options?: {
+        isProduction?: boolean;
+        hasBreakingChanges?: boolean;
+        skipConfirmation?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Shows operation summary and asks for final confirmation
+     */
+    static showOperationSummary(title: string, summary: Record<string, string | number | string[]>, options?: {
+        confirmationRequired?: boolean;
+        warningMessage?: string;
+    }): Promise<boolean>;
+    /**
+     * Interactive selection with confirmation
+     */
+    static selectWithConfirmation<T>(items: T[], options: {
+        message: string;
+        displayProperty?: keyof T;
+        multiSelect?: boolean;
+        confirmMessage?: string;
+        validator?: (selection: T[]) => string | true;
+    }): Promise<T[]>;
+    /**
+     * Confirms overwriting an existing file or directory
+     */
+    static confirmOverwrite(target: string): Promise<boolean>;
+    /**
+     * Confirms removal of a file
+     */
+    static confirmRemoval(target: string): Promise<boolean>;
+}