@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/admin-scripts/index.js

@@ -0,0 +1,52 @@
+/**
+ * Admin Scripts Module
+ *
+ * Exports repository interfaces and factories for admin script management.
+ * Concrete implementations support MongoDB, PostgreSQL, and DocumentDB.
+ *
+ * Repository interfaces follow the Port pattern in Hexagonal Architecture:
+ * - Define contracts for data access
+ * - Enable dependency injection
+ * - Allow testing with mocks
+ * - Support multiple database implementations
+ *
+ * Authentication:
+ * - Uses ENV-based ADMIN_API_KEY (see handlers/middleware/admin-auth.js)
+ * - No database-backed API keys (simplified from original design)
+ */
+
+// Repository Interfaces
+const { AdminScriptExecutionRepositoryInterface } = require('./repositories/admin-script-execution-repository-interface');
+const { ScriptScheduleRepositoryInterface } = require('./repositories/script-schedule-repository-interface');
+
+// Repository Factories
+const {
+    createAdminScriptExecutionRepository,
+    AdminScriptExecutionRepositoryMongo,
+    AdminScriptExecutionRepositoryPostgres,
+    AdminScriptExecutionRepositoryDocumentDB,
+} = require('./repositories/admin-script-execution-repository-factory');
+const {
+    createScriptScheduleRepository,
+    ScriptScheduleRepositoryMongo,
+    ScriptScheduleRepositoryPostgres,
+    ScriptScheduleRepositoryDocumentDB,
+} = require('./repositories/script-schedule-repository-factory');
+
+module.exports = {
+    // Repository Interfaces
+    AdminScriptExecutionRepositoryInterface,
+    ScriptScheduleRepositoryInterface,
+
+    // Repository Factories (primary exports for use cases)
+    createAdminScriptExecutionRepository,
+    createScriptScheduleRepository,
+
+    // Concrete Implementations (for testing)
+    AdminScriptExecutionRepositoryMongo,
+    AdminScriptExecutionRepositoryPostgres,
+    AdminScriptExecutionRepositoryDocumentDB,
+    ScriptScheduleRepositoryMongo,
+    ScriptScheduleRepositoryPostgres,
+    ScriptScheduleRepositoryDocumentDB,
+};

package/admin-scripts/repositories/admin-script-execution-repository-documentdb.js

@@ -0,0 +1,21 @@
+const {
+    AdminScriptExecutionRepositoryMongo,
+} = require('./admin-script-execution-repository-mongo');
+
+/**
+ * DocumentDB Admin Process Repository Adapter
+ * Extends MongoDB implementation since DocumentDB uses the same Prisma client
+ *
+ * DocumentDB-specific characteristics:
+ * - Uses MongoDB-compatible API
+ * - Prisma client handles the connection
+ * - IDs are strings with ObjectId format
+ * - All operations identical to MongoDB implementation
+ */
+class AdminScriptExecutionRepositoryDocumentDB extends AdminScriptExecutionRepositoryMongo {
+    constructor() {
+        super();
+    }
+}
+
+module.exports = { AdminScriptExecutionRepositoryDocumentDB };

package/admin-scripts/repositories/admin-script-execution-repository-factory.js

@@ -0,0 +1,51 @@
+const { AdminScriptExecutionRepositoryMongo } = require('./admin-script-execution-repository-mongo');
+const { AdminScriptExecutionRepositoryPostgres } = require('./admin-script-execution-repository-postgres');
+const {
+    AdminScriptExecutionRepositoryDocumentDB,
+} = require('./admin-script-execution-repository-documentdb');
+const config = require('../../database/config');
+
+/**
+ * Admin Process Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * This implements the Factory pattern for Hexagonal Architecture:
+ * - Reads database type from app definition (backend/index.js)
+ * - Returns correct adapter (MongoDB, DocumentDB, or PostgreSQL)
+ * - Provides clear error for unsupported databases
+ *
+ * Usage:
+ * ```javascript
+ * const repository = createAdminScriptExecutionRepository();
+ * ```
+ *
+ * @returns {AdminScriptExecutionRepositoryInterface} Configured repository adapter
+ * @throws {Error} If database type is not supported
+ */
+function createAdminScriptExecutionRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new AdminScriptExecutionRepositoryMongo();
+
+        case 'postgresql':
+            return new AdminScriptExecutionRepositoryPostgres();
+
+        case 'documentdb':
+            return new AdminScriptExecutionRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createAdminScriptExecutionRepository,
+    // Export adapters for direct testing
+    AdminScriptExecutionRepositoryMongo,
+    AdminScriptExecutionRepositoryPostgres,
+    AdminScriptExecutionRepositoryDocumentDB,
+};

package/admin-scripts/repositories/admin-script-execution-repository-interface.js

@@ -0,0 +1,171 @@
+/**
+ * Admin Process Repository Interface
+ * Abstract base class defining the contract for admin process persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * Admin processes track administrative operations including:
+ * - Admin script executions
+ * - Database migrations
+ * - Scheduled maintenance tasks
+ *
+ * The AdminScriptExecution model uses a flexible JSON storage pattern:
+ * - context: Input parameters, trigger info, audit data, script version
+ * - results: Output data, logs, metrics, error details
+ *
+ * @abstract
+ */
+class AdminScriptExecutionRepositoryInterface {
+    /**
+     * Create a new admin process record
+     *
+     * @param {Object} params - Process creation parameters
+     * @param {string} params.name - Name of the process (e.g., script name, migration name)
+     * @param {string} params.type - Type of process (e.g., 'ADMIN_SCRIPT', 'DB_MIGRATION')
+     * @param {Object} [params.context] - Context data (input, trigger, audit, script version)
+     * @param {string} [params.context.scriptVersion] - Version of the script
+     * @param {string} [params.context.trigger] - Trigger type ('MANUAL', 'SCHEDULED', 'QUEUE', 'WEBHOOK')
+     * @param {string} [params.context.mode] - Execution mode ('sync' or 'async')
+     * @param {Object} [params.context.input] - Input parameters
+     * @param {Object} [params.context.audit] - Audit information
+     * @param {string} [params.context.audit.apiKeyName] - Name of API key used
+     * @param {string} [params.context.audit.apiKeyLast4] - Last 4 chars of API key
+     * @param {string} [params.context.audit.ipAddress] - IP address of requester
+     * @param {string|number} [params.parentExecutionId] - ID of the execution that queued this one, for the parent/child hierarchy
+     * @returns {Promise<Object>} The created process record
+     * @abstract
+     */
+    async createExecution({ name, type, context, parentExecutionId }) {
+        throw new Error('Method createExecution must be implemented by subclass');
+    }
+
+    /**
+     * Find a process by its ID
+     *
+     * @param {string|number} id - The process ID
+     * @returns {Promise<Object|null>} The process record or null if not found
+     * @abstract
+     */
+    async findExecutionById(id) {
+        throw new Error(
+            'Method findExecutionById must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find all processes with a specific name
+     *
+     * @param {string} name - The process name to filter by
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Maximum number of results
+     * @param {number} [options.offset] - Number of results to skip
+     * @param {string} [options.sortBy] - Field to sort by
+     * @param {string} [options.sortOrder] - Sort order ('asc' or 'desc')
+     * @param {string} [options.state] - Optional state filter ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')
+     * @param {string} [options.type] - Optional type filter ('ADMIN_SCRIPT', 'REPORT', 'DB_MIGRATION')
+     * @param {Date} [options.from] - Optional lower bound (inclusive) on createdAt
+     * @param {Date} [options.to] - Optional upper bound (inclusive) on createdAt
+     * @returns {Promise<Array>} Array of process records
+     * @abstract
+     */
+    async findExecutionsByName(name, options = {}) {
+        throw new Error(
+            'Method findExecutionsByName must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find all processes with a specific state
+     *
+     * @param {string} state - State to filter by ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Maximum number of results
+     * @param {number} [options.offset] - Number of results to skip
+     * @param {string} [options.sortBy] - Field to sort by
+     * @param {string} [options.sortOrder] - Sort order ('asc' or 'desc')
+     * @returns {Promise<Array>} Array of process records
+     * @abstract
+     */
+    async findExecutionsByState(state, options = {}) {
+        throw new Error(
+            'Method findExecutionsByState must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Update the state of a process
+     *
+     * @param {string|number} id - The process ID
+     * @param {string} state - New state value ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')
+     * @returns {Promise<Object>} Updated process record
+     * @abstract
+     */
+    async updateExecutionState(id, state) {
+        throw new Error(
+            'Method updateExecutionState must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Update the results of a process
+     * Merges new results with existing results in the results JSON field
+     *
+     * @param {string|number} id - The process ID
+     * @param {Object} results - Results data to merge
+     * @param {Object} [results.output] - Output data from the process
+     * @param {Object} [results.error] - Error information
+     * @param {string} [results.error.name] - Error name/type
+     * @param {string} [results.error.message] - Error message
+     * @param {string} [results.error.stack] - Error stack trace
+     * @param {Object} [results.metrics] - Performance metrics
+     * @param {Date} [results.metrics.startTime] - Process start time
+     * @param {Date} [results.metrics.endTime] - Process end time
+     * @param {number} [results.metrics.durationMs] - Duration in milliseconds
+     * @returns {Promise<Object>} Updated process record
+     * @abstract
+     */
+    async updateExecutionResults(id, results) {
+        throw new Error(
+            'Method updateExecutionResults must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Append a log entry to a process's log array in results
+     *
+     * @param {string|number} id - The process ID
+     * @param {Object} logEntry - Log entry to append
+     * @param {string} logEntry.level - Log level ('debug', 'info', 'warn', 'error')
+     * @param {string} logEntry.message - Log message
+     * @param {Object} [logEntry.data] - Additional log data
+     * @param {string} logEntry.timestamp - ISO timestamp
+     * @returns {Promise<Object>} Updated process record
+     * @abstract
+     */
+    async appendExecutionLog(id, logEntry) {
+        throw new Error(
+            'Method appendExecutionLog must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete all processes older than a specific date
+     * Used for cleanup and retention policies
+     *
+     * @param {Date} date - Delete processes older than this date
+     * @param {Object} [options] - Deletion options
+     * @param {string} [options.type] - Optional type filter, so report vs script retention can diverge
+     * @returns {Promise<Object>} Deletion result with count
+     * @abstract
+     */
+    async deleteExecutionsOlderThan(date, options = {}) {
+        throw new Error(
+            'Method deleteExecutionsOlderThan must be implemented by subclass'
+        );
+    }
+}
+
+module.exports = { AdminScriptExecutionRepositoryInterface };

package/admin-scripts/repositories/admin-script-execution-repository-mongo.js

@@ -0,0 +1,238 @@
+const { prisma } = require('../../database/prisma');
+const {
+    AdminScriptExecutionRepositoryInterface,
+} = require('./admin-script-execution-repository-interface');
+
+/**
+ * MongoDB Admin Process Repository Adapter
+ * Handles admin process persistence using Prisma with MongoDB
+ *
+ * MongoDB-specific characteristics:
+ * - IDs are strings with @db.ObjectId
+ * - context and results are Json objects
+ * - Stores logs in results.logs array
+ */
+class AdminScriptExecutionRepositoryMongo extends AdminScriptExecutionRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Create a new admin process record
+     *
+     * @param {Object} params - Process creation parameters
+     * @param {string} params.name - Name of the process
+     * @param {string} params.type - Type of process (e.g., 'ADMIN_SCRIPT', 'DB_MIGRATION')
+     * @param {Object} [params.context] - Context data
+     * @returns {Promise<Object>} The created process record
+     */
+    async createExecution({ name, type, context = {}, parentExecutionId }) {
+        const data = {
+            name,
+            type,
+            context,
+            results: { logs: [] },
+            ...(parentExecutionId != null && { parentExecutionId }),
+        };
+
+        const process = await this.prisma.adminScriptExecution.create({
+            data,
+        });
+
+        return process;
+    }
+
+    /**
+     * Find a process by its ID
+     *
+     * @param {string} id - The process ID
+     * @returns {Promise<Object|null>} The process record or null if not found
+     */
+    async findExecutionById(id) {
+        const process = await this.prisma.adminScriptExecution.findUnique({
+            where: { id },
+        });
+
+        return process;
+    }
+
+    /**
+     * Find all processes with a specific name
+     *
+     * @param {string} name - The process name to filter by
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Maximum number of results
+     * @param {number} [options.offset] - Number of results to skip
+     * @param {string} [options.sortBy] - Field to sort by
+     * @param {string} [options.sortOrder] - Sort order ('asc' or 'desc')
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findExecutionsByName(name, options = {}) {
+        const {
+            limit,
+            offset,
+            sortBy = 'createdAt',
+            sortOrder = 'desc',
+            state,
+            type,
+            from,
+            to,
+        } = options;
+
+        const where = { name };
+        if (state) where.state = state;
+        if (type) where.type = type;
+        if (from || to) {
+            where.createdAt = {};
+            if (from) where.createdAt.gte = from;
+            if (to) where.createdAt.lte = to;
+        }
+
+        const processes = await this.prisma.adminScriptExecution.findMany({
+            where,
+            orderBy: { [sortBy]: sortOrder },
+            take: limit,
+            skip: offset,
+        });
+
+        return processes;
+    }
+
+    /**
+     * Find all processes with a specific state
+     *
+     * @param {string} state - State to filter by
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Maximum number of results
+     * @param {number} [options.offset] - Number of results to skip
+     * @param {string} [options.sortBy] - Field to sort by
+     * @param {string} [options.sortOrder] - Sort order ('asc' or 'desc')
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findExecutionsByState(state, options = {}) {
+        const {
+            limit,
+            offset,
+            sortBy = 'createdAt',
+            sortOrder = 'desc',
+        } = options;
+
+        const processes = await this.prisma.adminScriptExecution.findMany({
+            where: { state },
+            orderBy: { [sortBy]: sortOrder },
+            take: limit,
+            skip: offset,
+        });
+
+        return processes;
+    }
+
+    /**
+     * Update the state of a process
+     *
+     * @param {string} id - The process ID
+     * @param {string} state - New state value
+     * @returns {Promise<Object>} Updated process record
+     */
+    async updateExecutionState(id, state) {
+        const process = await this.prisma.adminScriptExecution.update({
+            where: { id },
+            data: { state },
+        });
+
+        return process;
+    }
+
+    /**
+     * Update the results of a process
+     * Merges new results with existing results
+     *
+     * @param {string} id - The process ID
+     * @param {Object} results - Results data to merge
+     * @returns {Promise<Object>} Updated process record
+     */
+    async updateExecutionResults(id, results) {
+        // Get current process to merge results
+        const currentProcess = await this.prisma.adminScriptExecution.findUnique({
+            where: { id },
+        });
+
+        if (!currentProcess) {
+            throw new Error(`AdminScriptExecution ${id} not found`);
+        }
+
+        // Merge new results with existing results
+        const mergedResults = {
+            ...(currentProcess.results || {}),
+            ...results,
+        };
+
+        const process = await this.prisma.adminScriptExecution.update({
+            where: { id },
+            data: { results: mergedResults },
+        });
+
+        return process;
+    }
+
+    /**
+     * Append a log entry to a process's log array in results
+     *
+     * @param {string} id - The process ID
+     * @param {Object} logEntry - Log entry to append
+     * @param {string} logEntry.level - Log level ('debug', 'info', 'warn', 'error')
+     * @param {string} logEntry.message - Log message
+     * @param {Object} [logEntry.data] - Additional log data
+     * @param {string} logEntry.timestamp - ISO timestamp
+     * @returns {Promise<Object>} Updated process record
+     */
+    async appendExecutionLog(id, logEntry) {
+        // Get current process
+        const process = await this.prisma.adminScriptExecution.findUnique({
+            where: { id },
+        });
+
+        if (!process) {
+            throw new Error(`AdminScriptExecution ${id} not found`);
+        }
+
+        // Get current results and logs
+        const results = process.results || {};
+        const logs = Array.isArray(results.logs) ? [...results.logs] : [];
+        logs.push(logEntry);
+
+        // Update with new logs array in results
+        const updated = await this.prisma.adminScriptExecution.update({
+            where: { id },
+            data: { results: { ...results, logs } },
+        });
+
+        return updated;
+    }
+
+    /**
+     * Delete all processes older than a specific date
+     * Used for cleanup and retention policies
+     *
+     * @param {Date} date - Delete processes older than this date
+     * @param {Object} [options] - Deletion options
+     * @param {string} [options.type] - Optional type filter
+     * @returns {Promise<Object>} Deletion result with count
+     */
+    async deleteExecutionsOlderThan(date, { type } = {}) {
+        const where = { createdAt: { lt: date } };
+        if (type) where.type = type;
+
+        const result = await this.prisma.adminScriptExecution.deleteMany({
+            where,
+        });
+
+        return {
+            acknowledged: true,
+            deletedCount: result.count,
+        };
+    }
+}
+
+module.exports = { AdminScriptExecutionRepositoryMongo };