@friggframework/admin-scripts 2.0.0--canary.517.41839c5.0

package/src/application/dry-run-repository-wrapper.js

@@ -0,0 +1,261 @@
+/**
+ * Dry-Run Repository Wrapper
+ *
+ * Wraps any repository to intercept write operations.
+ * - READ operations pass through unchanged
+ * - WRITE operations are logged but not executed
+ *
+ * Uses Proxy pattern for dynamic method interception
+ */
+
+/**
+ * Create a dry-run wrapper for any repository
+ *
+ * @param {Object} repository - The real repository to wrap
+ * @param {Array} operationLog - Array to append logged operations
+ * @param {string} modelName - Name of the model (for logging)
+ * @returns {Proxy} Wrapped repository that logs write operations
+ */
+function createDryRunWrapper(repository, operationLog, modelName) {
+    return new Proxy(repository, {
+        get(target, prop) {
+            const value = target[prop];
+
+            // Return non-function properties as-is
+            if (typeof value !== 'function') {
+                return value;
+            }
+
+            // Identify write operations by name pattern
+            const writePatterns = /^(create|update|delete|upsert|append|remove|insert|save)/i;
+            const isWrite = writePatterns.test(prop);
+
+            // Pass through read operations
+            if (!isWrite) {
+                return value.bind(target);
+            }
+
+            // Wrap write operation
+            return async (...args) => {
+                // Log the operation that WOULD have been performed
+                operationLog.push({
+                    operation: prop.toUpperCase(),
+                    model: modelName,
+                    method: prop,
+                    args: sanitizeArgs(args),
+                    timestamp: new Date().toISOString(),
+                    wouldExecute: `${modelName}.${prop}()`,
+                });
+
+                // For write operations, try to return existing data or mock data
+                // This helps scripts continue executing without errors
+
+                // For updates, try to return existing data
+                if (prop.includes('update') || prop.includes('upsert')) {
+                    // Try to extract ID from first argument
+                    const possibleId = args[0];
+                    let existing = null;
+
+                    if (possibleId && typeof possibleId === 'string') {
+                        // Try to find existing record
+                        const findMethod = getFindMethod(target, prop);
+                        if (findMethod) {
+                            try {
+                                existing = await findMethod.call(target, possibleId);
+                            } catch (err) {
+                                // Ignore errors, continue to mock
+                            }
+                        }
+                    }
+
+                    // Return merged data
+                    if (existing) {
+                        // Merge update data with existing
+                        return { ...existing, ...args[1], _dryRun: true };
+                    }
+
+                    // No existing data, return mock
+                    if (args[1]) {
+                        return { id: possibleId, ...args[1], _dryRun: true };
+                    }
+
+                    return { id: possibleId, _dryRun: true };
+                }
+
+                // For creates, return mock object with the data
+                if (prop.includes('create') || prop.includes('insert')) {
+                    const data = args[0] || {};
+                    return {
+                        id: `dry-run-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                        ...data,
+                        _dryRun: true,
+                        createdAt: new Date().toISOString(),
+                    };
+                }
+
+                // For deletes, return success indication
+                if (prop.includes('delete') || prop.includes('remove')) {
+                    return { deletedCount: 1, _dryRun: true };
+                }
+
+                // Default: return mock success
+                return { success: true, _dryRun: true };
+            };
+        },
+    });
+}
+
+/**
+ * Try to find a corresponding find method for an update operation
+ * @param {Object} target - Repository target
+ * @param {string} updateMethod - Update method name
+ * @returns {Function|null} Find method or null
+ */
+function getFindMethod(target, updateMethod) {
+    // Common patterns: updateIntegration -> findIntegrationById
+    const patterns = [
+        () => {
+            const match = updateMethod.match(/update(\w+)/i);
+            return match ? `find${match[1]}ById` : null;
+        },
+        () => {
+            const match = updateMethod.match(/update(\w+)/i);
+            return match ? `get${match[1]}ById` : null;
+        },
+        () => 'findById',
+        () => 'getById',
+    ];
+
+    for (const pattern of patterns) {
+        const methodName = pattern();
+        if (methodName && typeof target[methodName] === 'function') {
+            return target[methodName];
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Sanitize arguments for logging (remove sensitive data)
+ * @param {Array} args - Function arguments
+ * @returns {Array} Sanitized arguments
+ */
+function sanitizeArgs(args) {
+    return args.map((arg) => {
+        if (arg === null || arg === undefined) {
+            return arg;
+        }
+
+        if (typeof arg !== 'object') {
+            return arg;
+        }
+
+        if (Array.isArray(arg)) {
+            return arg.map((item) => sanitizeArgs([item])[0]);
+        }
+
+        // Sanitize object - remove sensitive fields
+        const sanitized = {};
+        for (const [key, value] of Object.entries(arg)) {
+            const lowerKey = key.toLowerCase();
+
+            // Skip sensitive fields
+            if (
+                lowerKey.includes('password') ||
+                lowerKey.includes('token') ||
+                lowerKey.includes('secret') ||
+                lowerKey.includes('key') ||
+                lowerKey.includes('auth')
+            ) {
+                sanitized[key] = '[REDACTED]';
+                continue;
+            }
+
+            // Recursively sanitize nested objects
+            if (typeof value === 'object' && value !== null) {
+                sanitized[key] = sanitizeArgs([value])[0];
+            } else {
+                sanitized[key] = value;
+            }
+        }
+
+        return sanitized;
+    });
+}
+
+/**
+ * Wrap AdminFriggCommands for dry-run mode
+ *
+ * @param {Object} realCommands - Real AdminFriggCommands instance
+ * @param {Array} operationLog - Array to append logged operations
+ * @returns {Object} Wrapped commands with dry-run repository wrappers
+ */
+function wrapAdminFriggCommandsForDryRun(realCommands, operationLog) {
+    return new Proxy(realCommands, {
+        get(target, prop) {
+            const value = target[prop];
+
+            // Pass through non-functions
+            if (typeof value !== 'function') {
+                // For lazy-loaded repositories, wrap them
+                if (prop.endsWith('Repository') && value && typeof value === 'object') {
+                    const modelName = prop.replace('Repository', '');
+                    return createDryRunWrapper(
+                        value,
+                        operationLog,
+                        modelName.charAt(0).toUpperCase() + modelName.slice(1)
+                    );
+                }
+                return value;
+            }
+
+            // Identify write operations on the commands themselves
+            const writePatterns = /^(update|create|delete|append)/i;
+            const isWrite = writePatterns.test(prop);
+
+            if (!isWrite) {
+                // Read operations pass through
+                return value.bind(target);
+            }
+
+            // Wrap write operations
+            return async (...args) => {
+                operationLog.push({
+                    operation: prop.toUpperCase(),
+                    source: 'AdminFriggCommands',
+                    method: prop,
+                    args: sanitizeArgs(args),
+                    timestamp: new Date().toISOString(),
+                });
+
+                // For specific known methods, try to return sensible mocks
+                if (prop === 'updateIntegrationConfig') {
+                    const [integrationId] = args;
+                    const existing = await target.findIntegrationById(integrationId);
+                    return existing;
+                }
+
+                if (prop === 'updateIntegrationStatus') {
+                    const [integrationId] = args;
+                    const existing = await target.findIntegrationById(integrationId);
+                    return existing;
+                }
+
+                if (prop === 'updateCredential') {
+                    const [credentialId, updates] = args;
+                    return { id: credentialId, ...updates, _dryRun: true };
+                }
+
+                // Default mock
+                return { success: true, _dryRun: true };
+            };
+        },
+    });
+}
+
+module.exports = {
+    createDryRunWrapper,
+    wrapAdminFriggCommandsForDryRun,
+    sanitizeArgs,
+};

package/src/application/schedule-management-use-case.js

@@ -0,0 +1,230 @@
+/**
+ * Schedule Management Use Case
+ *
+ * Application Layer - Hexagonal Architecture
+ *
+ * Orchestrates schedule management operations:
+ * - Get effective schedule (DB override > Definition > none)
+ * - Upsert schedule with EventBridge provisioning
+ * - Delete schedule with EventBridge cleanup
+ *
+ * This use case encapsulates the business logic that was previously
+ * embedded in the router, reducing cognitive complexity and improving testability.
+ */
+class ScheduleManagementUseCase {
+    constructor({ commands, schedulerAdapter, scriptFactory }) {
+        this.commands = commands;
+        this.schedulerAdapter = schedulerAdapter;
+        this.scriptFactory = scriptFactory;
+    }
+
+    /**
+     * Validate that a script exists
+     * @private
+     */
+    _validateScriptExists(scriptName) {
+        if (!this.scriptFactory.has(scriptName)) {
+            const error = new Error(`Script "${scriptName}" not found`);
+            error.code = 'SCRIPT_NOT_FOUND';
+            throw error;
+        }
+    }
+
+    /**
+     * Get the definition schedule from a script class
+     * @private
+     */
+    _getDefinitionSchedule(scriptName) {
+        const scriptClass = this.scriptFactory.get(scriptName);
+        return scriptClass.Definition?.schedule || null;
+    }
+
+    /**
+     * Get effective schedule (DB override > Definition default > none)
+     */
+    async getEffectiveSchedule(scriptName) {
+        this._validateScriptExists(scriptName);
+
+        // Check database override first
+        const dbSchedule = await this.commands.getScheduleByScriptName(scriptName);
+        if (dbSchedule) {
+            return {
+                source: 'database',
+                schedule: dbSchedule,
+            };
+        }
+
+        // Check definition default
+        const definitionSchedule = this._getDefinitionSchedule(scriptName);
+        if (definitionSchedule?.enabled) {
+            return {
+                source: 'definition',
+                schedule: {
+                    scriptName,
+                    enabled: definitionSchedule.enabled,
+                    cronExpression: definitionSchedule.cronExpression,
+                    timezone: definitionSchedule.timezone || 'UTC',
+                },
+            };
+        }
+
+        // No schedule configured
+        return {
+            source: 'none',
+            schedule: {
+                scriptName,
+                enabled: false,
+            },
+        };
+    }
+
+    /**
+     * Create or update schedule with EventBridge provisioning
+     */
+    async upsertSchedule(scriptName, { enabled, cronExpression, timezone }) {
+        this._validateScriptExists(scriptName);
+        this._validateScheduleInput(enabled, cronExpression);
+
+        // Save to database
+        const schedule = await this.commands.upsertSchedule({
+            scriptName,
+            enabled,
+            cronExpression: cronExpression || null,
+            timezone: timezone || 'UTC',
+        });
+
+        // Provision/deprovision EventBridge
+        const schedulerResult = await this._syncEventBridgeSchedule(
+            scriptName,
+            enabled,
+            cronExpression,
+            timezone,
+            schedule.awsScheduleArn
+        );
+
+        return {
+            success: true,
+            schedule: {
+                ...schedule,
+                awsScheduleArn: schedulerResult.awsScheduleArn || schedule.awsScheduleArn,
+                awsScheduleName: schedulerResult.awsScheduleName || schedule.awsScheduleName,
+            },
+            ...(schedulerResult.warning && { schedulerWarning: schedulerResult.warning }),
+        };
+    }
+
+    /**
+     * Validate schedule input
+     * @private
+     */
+    _validateScheduleInput(enabled, cronExpression) {
+        if (typeof enabled !== 'boolean') {
+            const error = new Error('enabled must be a boolean');
+            error.code = 'INVALID_INPUT';
+            throw error;
+        }
+
+        if (enabled && !cronExpression) {
+            const error = new Error('cronExpression is required when enabled is true');
+            error.code = 'INVALID_INPUT';
+            throw error;
+        }
+    }
+
+    /**
+     * Sync EventBridge schedule based on enabled state
+     * @private
+     */
+    async _syncEventBridgeSchedule(scriptName, enabled, cronExpression, timezone, existingArn) {
+        const result = { awsScheduleArn: null, awsScheduleName: null, warning: null };
+
+        try {
+            if (enabled && cronExpression) {
+                // Create/update EventBridge schedule
+                const awsInfo = await this.schedulerAdapter.createSchedule({
+                    scriptName,
+                    cronExpression,
+                    timezone: timezone || 'UTC',
+                });
+
+                if (awsInfo?.scheduleArn) {
+                    await this.commands.updateScheduleAwsInfo(scriptName, {
+                        awsScheduleArn: awsInfo.scheduleArn,
+                        awsScheduleName: awsInfo.scheduleName,
+                    });
+                    result.awsScheduleArn = awsInfo.scheduleArn;
+                    result.awsScheduleName = awsInfo.scheduleName;
+                }
+            } else if (!enabled && existingArn) {
+                // Delete EventBridge schedule
+                await this.schedulerAdapter.deleteSchedule(scriptName);
+                await this.commands.updateScheduleAwsInfo(scriptName, {
+                    awsScheduleArn: null,
+                    awsScheduleName: null,
+                });
+            }
+        } catch (error) {
+            // Non-fatal: DB schedule is saved, AWS can be retried
+            result.warning = error.message;
+        }
+
+        return result;
+    }
+
+    /**
+     * Delete schedule override and cleanup EventBridge
+     */
+    async deleteSchedule(scriptName) {
+        this._validateScriptExists(scriptName);
+
+        // Delete from database
+        const deleteResult = await this.commands.deleteSchedule(scriptName);
+
+        // Cleanup EventBridge if needed
+        const schedulerWarning = await this._cleanupEventBridgeSchedule(
+            scriptName,
+            deleteResult.deleted?.awsScheduleArn
+        );
+
+        // Get effective schedule after deletion
+        const definitionSchedule = this._getDefinitionSchedule(scriptName);
+        const effectiveSchedule = definitionSchedule?.enabled
+            ? {
+                source: 'definition',
+                enabled: definitionSchedule.enabled,
+                cronExpression: definitionSchedule.cronExpression,
+                timezone: definitionSchedule.timezone || 'UTC',
+            }
+            : { source: 'none', enabled: false };
+
+        return {
+            success: true,
+            deletedCount: deleteResult.deletedCount,
+            message: deleteResult.deletedCount > 0
+                ? 'Schedule override removed'
+                : 'No schedule override found',
+            effectiveSchedule,
+            ...(schedulerWarning && { schedulerWarning }),
+        };
+    }
+
+    /**
+     * Cleanup EventBridge schedule if it exists
+     * @private
+     */
+    async _cleanupEventBridgeSchedule(scriptName, awsScheduleArn) {
+        if (!awsScheduleArn) {
+            return null;
+        }
+
+        try {
+            await this.schedulerAdapter.deleteSchedule(scriptName);
+            return null;
+        } catch (error) {
+            // Non-fatal: DB is cleaned up, AWS can be retried
+            return error.message;
+        }
+    }
+}
+
+module.exports = { ScheduleManagementUseCase };

package/src/application/script-factory.js

@@ -0,0 +1,161 @@
+/**
+ * Script Factory
+ *
+ * Registry and factory for admin scripts.
+ * Manages script registration, validation, and instantiation.
+ *
+ * Usage:
+ * ```javascript
+ * const factory = new ScriptFactory();
+ * factory.register(MyScript);
+ * const script = factory.createInstance('my-script', { executionId: '123' });
+ * ```
+ */
+class ScriptFactory {
+    constructor(scripts = []) {
+        this.registry = new Map();
+
+        // Register initial scripts
+        scripts.forEach((ScriptClass) => this.register(ScriptClass));
+    }
+
+    /**
+     * Register a script class
+     * @param {Function} ScriptClass - Script class extending AdminScriptBase
+     * @throws {Error} If script invalid or name collision
+     */
+    register(ScriptClass) {
+        if (!ScriptClass || !ScriptClass.Definition) {
+            throw new Error('Script class must have a static Definition property');
+        }
+
+        const definition = ScriptClass.Definition;
+        const name = definition.name;
+
+        if (!name) {
+            throw new Error('Script Definition must have a name');
+        }
+
+        if (this.registry.has(name)) {
+            throw new Error(`Script "${name}" is already registered`);
+        }
+
+        this.registry.set(name, ScriptClass);
+    }
+
+    /**
+     * Register multiple scripts at once
+     * @param {Array} scriptClasses - Array of script classes
+     */
+    registerAll(scriptClasses) {
+        scriptClasses.forEach((ScriptClass) => this.register(ScriptClass));
+    }
+
+    /**
+     * Check if script is registered
+     * @param {string} name - Script name
+     * @returns {boolean} True if registered
+     */
+    has(name) {
+        return this.registry.has(name);
+    }
+
+    /**
+     * Get script class by name
+     * @param {string} name - Script name
+     * @returns {Function} Script class
+     * @throws {Error} If script not found
+     */
+    get(name) {
+        const ScriptClass = this.registry.get(name);
+        if (!ScriptClass) {
+            throw new Error(`Script "${name}" not found`);
+        }
+        return ScriptClass;
+    }
+
+    /**
+     * Get array of all registered script names
+     * @returns {Array<string>} Array of script names
+     */
+    getNames() {
+        return Array.from(this.registry.keys());
+    }
+
+    /**
+     * Get all registered scripts
+     * @returns {Array} Array of { name, definition, class }
+     */
+    getAll() {
+        const scripts = [];
+        for (const [name, ScriptClass] of this.registry.entries()) {
+            scripts.push({
+                name,
+                definition: ScriptClass.Definition,
+                class: ScriptClass,
+            });
+        }
+        return scripts;
+    }
+
+    /**
+     * Create script instance
+     * @param {string} name - Script name
+     * @param {Object} params - Constructor parameters
+     * @returns {Object} Script instance
+     * @throws {Error} If script not found
+     */
+    createInstance(name, params = {}) {
+        const ScriptClass = this.get(name);
+        return new ScriptClass(params);
+    }
+
+    /**
+     * Remove script from registry
+     * @param {string} name - Script name
+     * @returns {boolean} True if removed
+     */
+    unregister(name) {
+        return this.registry.delete(name);
+    }
+
+    /**
+     * Clear all registered scripts
+     */
+    clear() {
+        this.registry.clear();
+    }
+
+    /**
+     * Get count of registered scripts
+     * @returns {number} Count
+     */
+    get size() {
+        return this.registry.size;
+    }
+}
+
+// Singleton instance for global use
+let globalFactory = null;
+
+/**
+ * Get global script factory instance
+ * @returns {ScriptFactory} Global factory
+ */
+function getScriptFactory() {
+    if (!globalFactory) {
+        globalFactory = new ScriptFactory();
+    }
+    return globalFactory;
+}
+
+/**
+ * Create a new script factory instance
+ * @param {Array} scripts - Initial scripts to register
+ * @returns {ScriptFactory} New factory
+ */
+function createScriptFactory(scripts = []) {
+    return new ScriptFactory(scripts);
+}
+
+module.exports = { ScriptFactory, getScriptFactory, createScriptFactory };