@friggframework/core 2.0.0--canary.520.6641121.0 → 2.0.0--canary.517.35ee143.0

package/admin-scripts/repositories/script-schedule-repository-postgres.js

@@ -0,0 +1,210 @@
+const { prisma } = require('../../database/prisma');
+const {
+    ScriptScheduleRepositoryInterface,
+} = require('./script-schedule-repository-interface');
+
+/**
+ * PostgreSQL Script Schedule Repository Adapter
+ * Handles script schedule persistence using Prisma with PostgreSQL
+ *
+ * PostgreSQL-specific characteristics:
+ * - Uses Int IDs with autoincrement
+ * - Requires ID conversion: String (app layer) ↔ Int (database)
+ * - All returned IDs are converted to strings for application layer consistency
+ * - scriptName has unique index
+ */
+class ScriptScheduleRepositoryPostgres extends ScriptScheduleRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Convert string ID to integer for PostgreSQL queries
+     * @private
+     * @param {string|number|null|undefined} id - ID to convert
+     * @returns {number|null|undefined} Integer ID or null/undefined
+     * @throws {Error} If ID cannot be converted to integer
+     */
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        const parsed = Number.parseInt(id, 10);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+
+    /**
+     * Convert schedule object IDs to strings
+     * @private
+     * @param {Object|null} schedule - Schedule object from database
+     * @returns {Object|null} Schedule with string IDs
+     */
+    _convertScheduleIds(schedule) {
+        if (!schedule) return schedule;
+        return {
+            ...schedule,
+            id: schedule.id?.toString(),
+        };
+    }
+
+    /**
+     * Find a schedule by script name
+     *
+     * @param {string} scriptName - The script name
+     * @returns {Promise<Object|null>} Schedule record with string ID or null if not found
+     */
+    async findScheduleByScriptName(scriptName) {
+        const schedule = await this.prisma.scriptSchedule.findUnique({
+            where: { scriptName },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Create or update a schedule (upsert)
+     *
+     * @param {Object} params - Schedule parameters
+     * @param {string} params.scriptName - Name of the script
+     * @param {boolean} params.enabled - Whether schedule is enabled
+     * @param {string} params.cronExpression - Cron expression
+     * @param {string} [params.timezone] - Timezone (default 'UTC')
+     * @param {string} [params.externalScheduleId] - External scheduler ID (e.g., AWS ARN)
+     * @param {string} [params.externalScheduleName] - External scheduler name
+     * @returns {Promise<Object>} Created or updated schedule record with string ID
+     */
+    async upsertSchedule({ scriptName, enabled, cronExpression, timezone, externalScheduleId, externalScheduleName }) {
+        const data = {
+            enabled,
+            cronExpression,
+            timezone: timezone || 'UTC',
+        };
+
+        // Only set external scheduler fields if provided
+        if (externalScheduleId !== undefined) data.externalScheduleId = externalScheduleId;
+        if (externalScheduleName !== undefined) data.externalScheduleName = externalScheduleName;
+
+        const schedule = await this.prisma.scriptSchedule.upsert({
+            where: { scriptName },
+            update: data,
+            create: {
+                scriptName,
+                ...data,
+            },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Delete a schedule by script name
+     *
+     * @param {string} scriptName - The script name
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteSchedule(scriptName) {
+        try {
+            const schedule = await this.prisma.scriptSchedule.delete({
+                where: { scriptName },
+            });
+
+            return {
+                acknowledged: true,
+                deletedCount: 1,
+                deleted: this._convertScheduleIds(schedule),
+            };
+        } catch (error) {
+            // Return 0 count if not found
+            if (error.code === 'P2025') {
+                return {
+                    acknowledged: true,
+                    deletedCount: 0,
+                };
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Update external scheduler information
+     *
+     * @param {string} scriptName - The script name
+     * @param {Object} externalInfo - External schedule information
+     * @param {string} [externalInfo.externalScheduleId] - External scheduler ID (e.g., AWS ARN)
+     * @param {string} [externalInfo.externalScheduleName] - External scheduler name
+     * @returns {Promise<Object>} Updated schedule record with string ID
+     */
+    async updateScheduleExternalInfo(scriptName, { externalScheduleId, externalScheduleName }) {
+        const data = {};
+        if (externalScheduleId !== undefined) data.externalScheduleId = externalScheduleId;
+        if (externalScheduleName !== undefined) data.externalScheduleName = externalScheduleName;
+
+        const schedule = await this.prisma.scriptSchedule.update({
+            where: { scriptName },
+            data,
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Update last triggered timestamp
+     *
+     * @param {string} scriptName - The script name
+     * @param {Date} [timestamp] - Trigger timestamp (default: now)
+     * @returns {Promise<Object>} Updated schedule record with string ID
+     */
+    async updateScheduleLastTriggered(scriptName, timestamp) {
+        const schedule = await this.prisma.scriptSchedule.update({
+            where: { scriptName },
+            data: {
+                lastTriggeredAt: timestamp || new Date(),
+            },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Update next trigger timestamp
+     *
+     * @param {string} scriptName - The script name
+     * @param {Date} timestamp - Next trigger timestamp
+     * @returns {Promise<Object>} Updated schedule record with string ID
+     */
+    async updateScheduleNextTrigger(scriptName, timestamp) {
+        const schedule = await this.prisma.scriptSchedule.update({
+            where: { scriptName },
+            data: {
+                nextTriggerAt: timestamp,
+            },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * List all schedules
+     *
+     * @param {Object} [options] - Query options
+     * @param {boolean} [options.enabledOnly] - Only return enabled schedules
+     * @returns {Promise<Array>} Array of schedule records with string IDs
+     */
+    async listSchedules(options = {}) {
+        const where = {};
+        if (options.enabledOnly) {
+            where.enabled = true;
+        }
+
+        const schedules = await this.prisma.scriptSchedule.findMany({
+            where,
+            orderBy: { scriptName: 'asc' },
+        });
+
+        return schedules.map((schedule) => this._convertScheduleIds(schedule));
+    }
+}
+
+module.exports = { ScriptScheduleRepositoryPostgres };

package/application/commands/admin-script-commands.js

@@ -0,0 +1,344 @@
+const ERROR_CODE_MAP = {
+    SCRIPT_NOT_FOUND: 404,
+    EXECUTION_NOT_FOUND: 404,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return { error: status, reason: error?.message, code: error?.code };
+}
+
+/**
+ * Create admin script commands
+ * Provides command pattern API for admin script management
+ *
+ * This follows the Command pattern from integration-commands.js:
+ * - Creates repositories via factory functions
+ * - Maps errors to HTTP-friendly responses
+ * - Returns data or error objects (never throws)
+ *
+ * WHY SEPARATE FROM integration-commands.js:
+ * These commands are intentionally separate because they serve different domains:
+ * - integration-commands: User-context operations on integrations
+ *   - Requires integrationClass constructor parameter
+ *   - Works with userId, entityIds, integration contexts
+ *   - Uses IntegrationRepository, ModuleRepository
+ * - admin-script-commands: System/admin operations without user context
+ *   - No user context required
+ *   - Works with AdminProcess, ScriptSchedule
+ *   - Uses AdminProcessRepository, ScriptScheduleRepository
+ *
+ * Merging them would violate SRP and create coupling between
+ * user-facing integration code and admin/system code.
+ *
+ * Authentication:
+ * - Uses ENV-based ADMIN_API_KEY (see handlers/middleware/admin-auth.js)
+ * - No database-backed API keys (simplified from original design)
+ *
+ * @returns {Object} Command methods for admin scripts
+ */
+function createAdminScriptCommands() {
+    // Lazy-load repository factories to avoid circular dependencies
+    const { createAdminProcessRepository } = require('../../admin-scripts/repositories/admin-process-repository-factory');
+    const { createScriptScheduleRepository } = require('../../admin-scripts/repositories/script-schedule-repository-factory');
+
+    const adminProcessRepository = createAdminProcessRepository();
+    const scheduleRepository = createScriptScheduleRepository();
+
+    return {
+        // ==================== Admin Process Management Commands ====================
+
+        /**
+         * Create a new admin process record
+         *
+         * @param {Object} params - Process creation parameters
+         * @param {string} params.scriptName - Name of script being executed
+         * @param {string} [params.scriptVersion] - Script version
+         * @param {string} params.trigger - Trigger type ('MANUAL', 'SCHEDULED', 'QUEUE', 'WEBHOOK')
+         * @param {string} [params.mode] - Execution mode ('sync' or 'async', default 'async')
+         * @param {Object} [params.input] - Input parameters
+         * @param {Object} [params.audit] - Audit information (apiKeyName, apiKeyLast4, ipAddress)
+         * @returns {Promise<Object>} Created admin process record
+         */
+        async createAdminProcess({
+            scriptName,
+            scriptVersion,
+            trigger,
+            mode,
+            input,
+            audit,
+        }) {
+            try {
+                const process = await adminProcessRepository.createAdminProcess({
+                    scriptName,
+                    scriptVersion,
+                    trigger,
+                    mode: mode || 'async',
+                    input,
+                    audit,
+                });
+                return process;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find an admin process by ID
+         *
+         * @param {string|number} processId - The admin process ID
+         * @returns {Promise<Object>} Admin process record or error
+         */
+        async findAdminProcessById(processId) {
+            try {
+                const process = await adminProcessRepository.findAdminProcessById(processId);
+                if (!process) {
+                    const error = new Error(`Execution ${processId} not found`);
+                    error.code = 'EXECUTION_NOT_FOUND';
+                    return mapErrorToResponse(error);
+                }
+                return process;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find all admin processes for a specific script
+         *
+         * @param {string} scriptName - Script name to filter by
+         * @param {Object} [options] - Query options (limit, offset, sortBy, sortOrder)
+         * @returns {Promise<Array>} Array of admin process records
+         */
+        async findAdminProcessesByName(scriptName, options = {}) {
+            try {
+                const processes = await adminProcessRepository.findAdminProcessesByName(
+                    scriptName,
+                    options
+                );
+                return processes;
+            } catch (error) {
+                // Return empty array on error (non-critical)
+                return [];
+            }
+        },
+
+        /**
+         * Update admin process state
+         *
+         * @param {string|number} processId - The admin process ID
+         * @param {string} state - New state ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')
+         * @returns {Promise<Object>} Updated admin process record
+         */
+        async updateAdminProcessState(processId, state) {
+            try {
+                const updated = await adminProcessRepository.updateAdminProcessState(
+                    processId,
+                    state
+                );
+                return updated;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Append a log entry to an admin process's results.logs array
+         *
+         * @param {string|number} processId - The admin process ID
+         * @param {Object} logEntry - Log entry { level, message, data, timestamp }
+         * @returns {Promise<Object>} Updated admin process record
+         */
+        async appendAdminProcessLog(processId, logEntry) {
+            try {
+                const updated = await adminProcessRepository.appendAdminProcessLog(
+                    processId,
+                    logEntry
+                );
+                return updated;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Complete an admin process
+         * Updates state, output, error, and metrics
+         *
+         * @param {string|number} processId - The admin process ID
+         * @param {Object} params - Completion parameters
+         * @param {string} [params.state] - Final state ('COMPLETED', 'FAILED')
+         * @param {Object} [params.output] - Script output/result (stored in results.output)
+         * @param {Object} [params.error] - Error details { name, message, stack } (stored in results.error)
+         * @param {Object} [params.metrics] - Performance metrics { startTime, endTime, durationMs } (stored in results.metrics)
+         * @returns {Promise<Object>} { success: true } or error
+         */
+        async completeAdminProcess(processId, { state, output, error, metrics }) {
+            try {
+                // Update each field independently (partial updates allowed)
+                if (state) {
+                    await adminProcessRepository.updateAdminProcessState(processId, state);
+                }
+                if (output !== undefined) {
+                    await adminProcessRepository.updateAdminProcessOutput(processId, output);
+                }
+                if (error) {
+                    await adminProcessRepository.updateAdminProcessError(processId, error);
+                }
+                if (metrics) {
+                    await adminProcessRepository.updateAdminProcessMetrics(processId, metrics);
+                }
+
+                return { success: true };
+            } catch (err) {
+                return mapErrorToResponse(err);
+            }
+        },
+
+        /**
+         * Find recent admin processes across all scripts
+         *
+         * @param {Object} [options] - Query options
+         * @param {number} [options.limit] - Maximum results (default 20)
+         * @param {string} [options.state] - Filter by state
+         * @param {Date} [options.since] - Filter by created date
+         * @returns {Promise<Array>} Array of recent admin processes
+         */
+        async findRecentAdminProcesses(options = {}) {
+            try {
+                const { limit = 20, state, since } = options;
+
+                // If state filter provided, use state query
+                if (state) {
+                    return await adminProcessRepository.findAdminProcessesByState(state, {
+                        limit,
+                        sortBy: 'createdAt',
+                        sortOrder: 'desc',
+                    });
+                }
+
+                // Otherwise, use generic recent query (would need to be added to interface)
+                // For now, fall back to empty array if no state filter
+                return [];
+            } catch (error) {
+                return [];
+            }
+        },
+
+        // ==================== Schedule Management Commands ====================
+
+        /**
+         * Get schedule by script name
+         * Returns database override or null
+         *
+         * @param {string} scriptName - The script name
+         * @returns {Promise<Object|null>} Schedule record or null
+         */
+        async getScheduleByScriptName(scriptName) {
+            try {
+                const schedule = await scheduleRepository.findScheduleByScriptName(scriptName);
+                return schedule;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Create or update a schedule (upsert)
+         *
+         * @param {Object} params - Schedule parameters
+         * @param {string} params.scriptName - Name of the script
+         * @param {boolean} params.enabled - Whether schedule is enabled
+         * @param {string} params.cronExpression - Cron expression
+         * @param {string} [params.timezone] - Timezone (default 'UTC')
+         * @returns {Promise<Object>} Created or updated schedule
+         */
+        async upsertSchedule({ scriptName, enabled, cronExpression, timezone }) {
+            try {
+                const schedule = await scheduleRepository.upsertSchedule({
+                    scriptName,
+                    enabled,
+                    cronExpression,
+                    timezone,
+                });
+                return schedule;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Delete a schedule by script name
+         *
+         * @param {string} scriptName - The script name
+         * @returns {Promise<Object>} Deletion result
+         */
+        async deleteSchedule(scriptName) {
+            try {
+                const result = await scheduleRepository.deleteSchedule(scriptName);
+                return result;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Update external scheduler information
+         *
+         * @param {string} scriptName - The script name
+         * @param {Object} externalInfo - External schedule information
+         * @param {string} [externalInfo.externalScheduleId] - External scheduler ID (e.g., AWS ARN)
+         * @param {string} [externalInfo.externalScheduleName] - External scheduler name
+         * @returns {Promise<Object>} Updated schedule
+         */
+        async updateScheduleExternalInfo(scriptName, { externalScheduleId, externalScheduleName }) {
+            try {
+                const schedule = await scheduleRepository.updateScheduleExternalInfo(scriptName, {
+                    externalScheduleId,
+                    externalScheduleName,
+                });
+                return schedule;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Update last triggered timestamp
+         * Called when a schedule triggers
+         *
+         * @param {string} scriptName - The script name
+         * @param {Date} [timestamp] - Trigger timestamp (default: now)
+         * @returns {Promise<Object>} Updated schedule
+         */
+        async updateScheduleLastTriggered(scriptName, timestamp) {
+            try {
+                const schedule = await scheduleRepository.updateScheduleLastTriggered(
+                    scriptName,
+                    timestamp
+                );
+                return schedule;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * List all schedules
+         *
+         * @param {Object} [options] - Query options
+         * @param {boolean} [options.enabledOnly] - Only return enabled schedules
+         * @returns {Promise<Array>} Array of schedule records
+         */
+        async listSchedules(options = {}) {
+            try {
+                const schedules = await scheduleRepository.listSchedules(options);
+                return schedules;
+            } catch (error) {
+                return [];
+            }
+        },
+    };
+}
+
+module.exports = { createAdminScriptCommands };

package/database/use-cases/check-database-state-use-case.js

@@ -62,12 +62,12 @@ class CheckDatabaseStateUseCase {
         // Add error if present
         if (state.error) {
             response.error = state.error;
-            response.recommendation = 'Run POST /db-migrate to initialize database';
+            response.recommendation = 'Run POST /admin/db-migrate to initialize database';
         }
 
         // Add recommendation if migrations pending
         if (!state.upToDate && state.pendingMigrations > 0) {
-            response.recommendation = `Run POST /db-migrate to apply ${state.pendingMigrations} pending migration(s)`;
+            response.recommendation = `Run POST /admin/db-migrate to apply ${state.pendingMigrations} pending migration(s)`;
         }
 
         return response;

package/database/use-cases/trigger-database-migration-use-case.js

@@ -99,7 +99,7 @@ class TriggerDatabaseMigrationUseCase {
             success: true,
             migrationId: migrationStatus.migrationId,
             state: migrationStatus.state,
-            statusUrl: `/db-migrate/${migrationStatus.migrationId}`,
+            statusUrl: `/admin/db-migrate/${migrationStatus.migrationId}`,
             s3Key: `migrations/${migrationStatus.stage}/${migrationStatus.migrationId}.json`,
             message: 'Database migration queued successfully',
         };