@cyberismo/data-handler 0.0.17 → 0.0.19

package/dist/migrations/migration-executor.js

@@ -0,0 +1,312 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { availableMigrations, migration } from '@cyberismo/migrations';
+import { availableSpace, folderSize } from '../utils/file-utils.js';
+import { executeStep } from './worker-executor.js';
+import { getChildLogger } from '../utils/log-utils.js';
+import { Validate } from '../commands/validate.js';
+const DEFAULT_MIGRATION_TIMEOUT_MS = 2 * 60 * 1000; // 2 minutes
+const MEGABYTES = 1024 * 1024; // 1 MB
+/**
+ * Executes schema migrations for a project.
+ */
+export class MigrationExecutor {
+    project;
+    backupDir;
+    logger = getChildLogger({ module: 'MigrationExecutor' });
+    timeoutMilliSeconds;
+    /**
+     * Constructs instance of MigrationExecutor
+     * @param project Project instance to use
+     * @param backupDir Backup directory, if any.
+     * @param timeoutMilliSeconds Timeout in milliseconds (defaults to 2 minutes)
+     */
+    constructor(project, backupDir, timeoutMilliSeconds) {
+        this.project = project;
+        this.backupDir = backupDir;
+        this.timeoutMilliSeconds =
+            timeoutMilliSeconds ?? DEFAULT_MIGRATION_TIMEOUT_MS;
+    }
+    // Helper to create failure result from ExecutionState
+    createFailureResult(state, message, error) {
+        return {
+            success: false,
+            message,
+            error,
+            stepsExecuted: state.stepsExecuted,
+        };
+    }
+    // Execute a single migration step and handle failure
+    async executeStep(stepName, migrationPath, state) {
+        const result = await executeStep(migrationPath, stepName, state.context, this.timeoutMilliSeconds);
+        state.stepsExecuted.push(stepName);
+        if (!result.success) {
+            const messagePrefix = {
+                before: 'Pre-migration check failed',
+                backup: 'Backup failed',
+                migrate: 'Migration failed',
+                after: 'Post-migration step failed',
+            }[stepName] || `Step '${stepName}' failed`;
+            return this.createFailureResult(state, `${messagePrefix}: ${result.message || 'Unknown error'}`, result.error);
+        }
+        return { success: true };
+    }
+    // Execute a single migration.
+    async executeMigration(migrationPath, fromVersion, toVersion, updateVersionCallback) {
+        this.logger.info({ fromVersion, toVersion }, `Executing migration from version ${fromVersion} to ${toVersion}`);
+        const state = {
+            context: {
+                cardRootPath: this.project.paths.cardRootFolder,
+                cardsConfigPath: this.project.paths.internalRootFolder,
+                fromVersion,
+                toVersion,
+            },
+            stepsExecuted: [],
+        };
+        try {
+            // Load migration to check which steps exist
+            const migration = this.loadMigration(toVersion);
+            if (!migration) {
+                return this.createFailureResult(state, `Failed to load migration for version ${toVersion}`);
+            }
+            if (migration.before) {
+                const result = await this.executeStep('before', migrationPath, state);
+                if (!result.success)
+                    return result;
+            }
+            if (migration.backup && this.backupDir !== undefined) {
+                state.context.backupDir = this.backupDir;
+                const result = await this.executeStep('backup', migrationPath, state);
+                if (!result.success)
+                    return result;
+            }
+            const migrateResult = await this.executeStep('migrate', migrationPath, state);
+            if (!migrateResult.success)
+                return migrateResult;
+            // Update schema version in project after successful migration
+            await updateVersionCallback(toVersion);
+            state.stepsExecuted.push('update-version');
+            if (migration.after) {
+                const result = await this.executeStep('after', migrationPath, state);
+                if (!result.success)
+                    return result;
+            }
+            // Run validation after migration
+            state.stepsExecuted.push('validate');
+            const validationErrors = await this.validate();
+            if (validationErrors) {
+                return this.createFailureResult(state, `Post-migration validation failed: ${validationErrors}`);
+            }
+            this.logger.info('Post-migration validation passed');
+            return {
+                success: true,
+                message: `Successfully migrated from version ${fromVersion} to ${toVersion}`,
+                stepsExecuted: state.stepsExecuted,
+            };
+        }
+        catch (error) {
+            return this.createFailureResult(state, `Migration threw an exception: ${error}`, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    // Checks if pre-migration validation succeeds.
+    async preMigrateValidation(fromVersion, toVersion, stepsExecuted) {
+        const validationErrors = await this.validate();
+        if (validationErrors) {
+            this.logger.error({ errors: validationErrors }, 'Pre-migration validation failed');
+            return {
+                success: false,
+                message: `Pre-migration validation failed. Please fix the following errors before migrating:\n${validationErrors}`,
+                stepsExecuted,
+            };
+        }
+        this.logger.info('Pre-migration validation passed');
+        return {
+            success: true,
+            stepsExecuted,
+        };
+    }
+    // Validate the project.
+    async validate() {
+        const validator = Validate.getInstance();
+        return await validator.validate(this.project.basePath, () => this.project);
+    }
+    // Validates that migration versions are valid.
+    validateMigrationVersions(fromVersion, toVersion, stepsExecuted) {
+        const valid = fromVersion < toVersion;
+        return {
+            success: valid,
+            message: valid
+                ? undefined
+                : `Current version (${fromVersion}) is not lower than target version (${toVersion})`,
+            stepsExecuted,
+        };
+    }
+    // Checks if there is enough disk space.
+    async checkDiskSpace(fromVersion, toVersion, stepsExecuted) {
+        try {
+            const internalSize = await folderSize(this.project.paths.internalRootFolder);
+            const cardRootSize = await folderSize(this.project.paths.cardRootFolder);
+            const projectSize = internalSize + cardRootSize;
+            const requiredSpace = projectSize * 2;
+            const spaceAvailable = await availableSpace(this.project.basePath);
+            const projectSizeMB = (projectSize / MEGABYTES).toFixed(2);
+            const requiredSpaceMB = (requiredSpace / MEGABYTES).toFixed(2);
+            const availableSpaceMB = (spaceAvailable / MEGABYTES).toFixed(2);
+            if (spaceAvailable < requiredSpace) {
+                return {
+                    success: false,
+                    message: `Insufficient disk space. Required: ${requiredSpaceMB} MB, Available: ${availableSpaceMB} MB. Migration needs at least 2x the project size (${projectSizeMB} MB).`,
+                    stepsExecuted,
+                };
+            }
+            this.logger.info('Disk space check passed');
+            return {
+                success: true,
+                stepsExecuted,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error }, 'Failed to check disk space');
+            return {
+                success: false,
+                message: `Failed to check disk space: ${error instanceof Error ? error.message : String(error)}`,
+                error: error instanceof Error ? error : new Error(String(error)),
+                stepsExecuted,
+            };
+        }
+    }
+    /**
+     * Discover available migrations between two versions.
+     * @param fromVersion Starting version (exclusive)
+     * @param toVersion Target version (inclusive)
+     * @returns Sorted list of migration version numbers
+     */
+    migrationsAvailable(fromVersion, toVersion) {
+        const allVersions = availableMigrations();
+        return allVersions.filter((version) => version > fromVersion && version <= toVersion);
+    }
+    // Validates and discovers available migrations
+    availableMigrations(fromVersion, toVersion, stepsExecuted) {
+        const migrationVersions = this.migrationsAvailable(fromVersion, toVersion);
+        const found = migrationVersions.length > 0;
+        if (found) {
+            this.logger.info({ versions: migrationVersions }, `Found ${migrationVersions.length} migration(s)`);
+        }
+        return {
+            success: found,
+            message: found
+                ? undefined
+                : `No migrations found between version ${fromVersion} and ${toVersion}`,
+            stepsExecuted,
+            migrationVersions,
+        };
+    }
+    // Load a migration module for a specific version.
+    loadMigration(version) {
+        this.logger.debug({ version }, 'Loading migration');
+        try {
+            const migrationObject = migration(version);
+            if (!migrationObject) {
+                this.logger.error({ version }, `Migration not found`);
+                return undefined;
+            }
+            if (typeof migrationObject.migrate !== 'function') {
+                throw new Error(`Migration ${version} does not implement migrate() function`);
+            }
+            return migrationObject;
+        }
+        catch (error) {
+            this.logger.error({ error, version }, `Failed to load migration`);
+            return undefined;
+        }
+    }
+    /**
+     * Get the file path for a migration worker.
+     * @param version Migration version number
+     * @returns Path to migration file
+     */
+    migrationWorkerPath(version) {
+        const migrationsPackageUrl = import.meta.resolve('@cyberismo/migrations');
+        const migrationsIndexPath = fileURLToPath(migrationsPackageUrl);
+        const migrationsDistDir = dirname(migrationsIndexPath);
+        return join(migrationsDistDir, version.toString(), 'index.js');
+    }
+    /**
+     * Execute all necessary migrations to bring project to target version.
+     * @param fromVersion Current project version
+     * @param toVersion Target version
+     * @param updateVersionCallback Callback to update project schema version after each migration
+     * @returns Overall migration result
+     */
+    async migrate(fromVersion, toVersion, updateVersionCallback) {
+        const stepsDone = [];
+        // Step: Validate migration versions
+        const versionResult = this.validateMigrationVersions(fromVersion, toVersion, stepsDone);
+        if (!versionResult.success)
+            return versionResult;
+        stepsDone.push('version-validation');
+        // Step: Pre-migration validation
+        const validationResult = await this.preMigrateValidation(fromVersion, toVersion, stepsDone);
+        if (!validationResult.success)
+            return validationResult;
+        stepsDone.push('pre-validation');
+        // Step: Check disk space
+        const diskSpaceResult = await this.checkDiskSpace(fromVersion, toVersion, stepsDone);
+        if (!diskSpaceResult.success)
+            return diskSpaceResult;
+        stepsDone.push('disk-space-check');
+        // Step: Discover available migrations
+        const discoveryResult = this.availableMigrations(fromVersion, toVersion, stepsDone);
+        if (!discoveryResult.success)
+            return discoveryResult;
+        stepsDone.push('migration-versions');
+        const migrationVersions = discoveryResult.migrationVersions;
+        // Step(s): Execute migrations in sequence
+        let currentVersion = fromVersion;
+        try {
+            for (const targetVersion of migrationVersions) {
+                const migrationPath = this.migrationWorkerPath(targetVersion);
+                const result = await this.executeMigration(migrationPath, currentVersion, targetVersion, updateVersionCallback);
+                if (!result.success) {
+                    return {
+                        success: false,
+                        message: result.message || 'Migration failed',
+                        error: result.error,
+                        stepsExecuted: stepsDone,
+                    };
+                }
+                stepsDone.push(...result.stepsExecuted.map((step) => `v${targetVersion}:${step}`));
+                currentVersion = targetVersion;
+                this.logger.info({ targetVersion }, `Migration to version ${targetVersion} completed successfully`);
+            }
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: error instanceof Error
+                    ? error.message
+                    : `Migration timeout or error: ${error}`,
+                error: error instanceof Error ? error : new Error(String(error)),
+                stepsExecuted: stepsDone,
+            };
+        }
+        return {
+            success: true,
+            message: `Successfully migrated from version ${fromVersion} to ${currentVersion}`,
+            stepsExecuted: stepsDone,
+        };
+    }
+}
+//# sourceMappingURL=migration-executor.js.map

package/dist/migrations/migration-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-executor.js","sourceRoot":"","sources":["../../src/migrations/migration-executor.ts"],"names":[],"mappings":"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"}

package/dist/migrations/migration-worker.d.ts

@@ -0,0 +1,13 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+export {};

package/dist/migrations/migration-worker.js

@@ -0,0 +1,156 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { parentPort } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+let currentMigration;
+let abortController;
+/**
+ * Execute a specific step of a migration.
+ *
+ * Runs one of the migration steps (before, backup, migrate, after).
+ * Checks for cancellation before and after execution.
+ *
+ * @param migration The loaded migration object
+ * @param stepName Which step to execute ('before', 'backup', 'migrate', or 'after')
+ * @param context Migration context with paths and version information
+ * @returns Migration step result
+ */
+async function executeStep(migration, stepName, context) {
+    if (abortController?.signal.aborted) {
+        return {
+            success: false,
+            error: new Error('Migration cancelled'),
+        };
+    }
+    try {
+        let result;
+        switch (stepName) {
+            case 'before':
+                if (!migration.before) {
+                    return { success: true, message: `No 'before' step` };
+                }
+                result = await migration.before(context);
+                break;
+            case 'backup':
+                if (!migration.backup) {
+                    return { success: true, message: `No 'backup' step` };
+                }
+                result = await migration.backup(context);
+                break;
+            case 'migrate':
+                result = await migration.migrate(context);
+                break;
+            case 'after':
+                if (!migration.after) {
+                    return { success: true, message: `No 'after' step` };
+                }
+                result = await migration.after(context);
+                break;
+            default:
+                return {
+                    success: false,
+                    error: new Error(`Unknown migration step: ${stepName}`),
+                };
+        }
+        if (abortController?.signal.aborted) {
+            return {
+                success: false,
+                error: new Error('Migration cancelled'),
+            };
+        }
+        return result;
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+/**
+ * Handle a cancellation request from the main thread.
+ */
+async function handleCancel() {
+    abortController?.abort();
+    if (currentMigration?.cancel) {
+        try {
+            await currentMigration.cancel();
+        }
+        catch {
+            // Ignore errors during cancellation - we're cancelling anyway
+        }
+    }
+}
+/**
+ * Worker thread message handler.
+ *
+ * Listens for messages from the main thread:
+ * - 'execute': Run a migration step
+ * - 'cancel': Cancel the currently running migration
+ *
+ * Responds with:
+ * - 'result': The migration step result
+ * - 'error': An error message when execution failed
+ */
+if (parentPort) {
+    parentPort.on('message', (message) => {
+        if (!parentPort)
+            return;
+        void (async () => {
+            try {
+                if (message.type === 'cancel') {
+                    await handleCancel();
+                    const response = {
+                        type: 'result',
+                        result: {
+                            success: false,
+                            error: new Error('Migration cancelled'),
+                        },
+                    };
+                    parentPort.postMessage(response);
+                    return;
+                }
+                if (message.type === 'execute') {
+                    if (!message.migrationPath || !message.stepName || !message.context) {
+                        throw new Error('Missing required parameters for "execute"');
+                    }
+                    abortController = new AbortController();
+                    const migrationUrl = pathToFileURL(message.migrationPath).href;
+                    const migrationModule = await import(migrationUrl);
+                    currentMigration = migrationModule.default || migrationModule;
+                    if (typeof currentMigration?.migrate !== 'function') {
+                        throw new Error(`Migration does not implement migrate() function: ${message.migrationPath}`);
+                    }
+                    const contextWithSignal = {
+                        ...message.context,
+                        signal: abortController.signal,
+                    };
+                    const result = await executeStep(currentMigration, message.stepName, contextWithSignal);
+                    const response = {
+                        type: 'result',
+                        result,
+                    };
+                    parentPort.postMessage(response);
+                }
+            }
+            catch (error) {
+                const response = {
+                    type: 'error',
+                    error: error instanceof Error ? error.message : String(error),
+                };
+                parentPort.postMessage(response);
+            }
+        })();
+    });
+}
+//# sourceMappingURL=migration-worker.js.map

package/dist/migrations/migration-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-worker.js","sourceRoot":"","sources":["../../src/migrations/migration-worker.ts"],"names":[],"mappings":"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"}

package/dist/migrations/worker-executor.d.ts

@@ -0,0 +1,24 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import type { MigrationContext, MigrationStepResult } from '@cyberismo/migrations';
+/**
+ * Execute a migration step in a separate worker thread.
+ * The worker loads the migration program dynamically and executes the specified step.
+ *
+ * @param migrationPath Absolute path to the migration's 'index.js' file
+ * @param stepName The migration step to execute
+ * @param context Migration context
+ * @param timeoutMilliSeconds Timeout in milliseconds to wait for the step to complete
+ * @returns Migration step result
+ */
+export declare function executeStep(migrationPath: string, stepName: string, context: MigrationContext, timeoutMilliSeconds: number): Promise<MigrationStepResult>;