feat: provider plugin architecture + Netlify adapter

packages/core/handlers/app-definition-loader.js

@@ -3,16 +3,25 @@ const path = require('node:path');
 const fs = require('fs-extra');
 
 /**
- * Loads the App definition from the nearest backend package
+ * Loads the App definition from the nearest backend package.
+ *
+ * Returns the full appDefinition object plus convenience destructured fields
+ * for backward compatibility (integrations, userConfig).
+ *
  * @function loadAppDefinition
- * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
- * and extracts the application definition containing integrations and user configuration.
- * @returns {{integrations: Array<object>, userConfig: object | null}} An object containing the application definition.
- * @throws {Error} Throws error if backend package.json cannot be found.
- * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
+ * @returns {{
+ *   integrations: Array<object>,
+ *   userConfig: object | null,
+ *   appDefinition: object
+ * }}
+ * @throws {Error} If backend package.json or index.js cannot be found.
  * @example
- * const { integrations, userConfig } = loadAppDefinition();
- * console.log(`Found ${integrations.length} integrations`);
+ *   // Existing callers still work:
+ *   const { integrations, userConfig } = loadAppDefinition();
+ *
+ *   // New callers can access the full definition:
+ *   const { appDefinition } = loadAppDefinition();
+ *   console.log(appDefinition.provider); // 'aws' | 'netlify'
  */
 function loadAppDefinition() {
     const backendPath = findNearestBackendPackageJson();
@@ -30,7 +39,7 @@ function loadAppDefinition() {
     const appDefinition = backendJsFile.Definition;
 
     const { integrations = [], user: userConfig = null } = appDefinition;
-    return { integrations, userConfig };
+    return { integrations, userConfig, appDefinition };
 }
 
 module.exports = {

packages/core/index.js

@@ -92,7 +92,19 @@ const utils = require('./utils');
 
 // const {Sync } = require('./syncs/model');
 
-const { QueuerUtil } = require('./queues');
+const {
+    QueuerUtil,
+    QueueProvider,
+    createQueueProvider,
+    QUEUE_PROVIDERS,
+} = require('./queues');
+
+const {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+} = require('./providers');
 
 module.exports = {
     // assertions
@@ -187,6 +199,15 @@ module.exports = {
     ModuleFactory,
     // queues
     QueuerUtil,
+    QueueProvider,
+    createQueueProvider,
+    QUEUE_PROVIDERS,
+
+    // providers
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
 
     // utils
     ...utils,

packages/core/infrastructure/scheduler/index.js

@@ -5,13 +5,15 @@
  * Follows hexagonal architecture with interface + adapters pattern.
  *
  * Providers:
- * - eventbridge: AWS EventBridge Scheduler (production)
+ * - eventbridge: AWS EventBridge Scheduler (production on AWS)
+ * - netlify: Netlify poll-and-dispatch scheduler (production on Netlify)
  * - mock: In-memory mock scheduler (local development)
  */
 
 const { SchedulerServiceInterface } = require('./scheduler-service-interface');
 const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
 const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
+const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
 const {
     createSchedulerService,
     SCHEDULER_PROVIDERS,
@@ -25,6 +27,7 @@ module.exports = {
     // Adapters
     EventBridgeSchedulerAdapter,
     MockSchedulerAdapter,
+    NetlifySchedulerAdapter,
 
     // Factory
     createSchedulerService,

packages/core/infrastructure/scheduler/netlify-scheduler-adapter.js

@@ -0,0 +1,173 @@
+/**
+ * Netlify Scheduler Adapter
+ *
+ * Implements SchedulerServiceInterface for Netlify deployments.
+ *
+ * Netlify Scheduled Functions use cron syntax but are defined statically in
+ * netlify.toml or via the @netlify/functions schedule() helper. They cannot
+ * be created dynamically at runtime like EventBridge Scheduler.
+ *
+ * Strategy for one-time scheduled jobs on Netlify:
+ *   1. Store the schedule in the database (same as mock adapter pattern)
+ *   2. A Netlify Scheduled Function runs on a cron interval (e.g., every 5 min)
+ *   3. The cron function queries for due schedules and dispatches them
+ *      to a background function for execution
+ *
+ * This is a "poll-and-dispatch" pattern vs EventBridge's "push" pattern.
+ * Trade-off: slightly less precise timing (up to cron interval delay),
+ * but works on any platform without cloud-specific scheduling APIs.
+ *
+ * For integrations that need the queue provider to dispatch jobs:
+ *   - queueResourceId maps to the background function URL path
+ *   - Payload is stored and forwarded when the cron fires
+ */
+
+const { SchedulerServiceInterface } = require('./scheduler-service-interface');
+
+class NetlifySchedulerAdapter extends SchedulerServiceInterface {
+    /**
+     * @param {Object} options
+     * @param {Object} options.repository - Repository for persisting schedules
+     *   Must implement: save(schedule), delete(scheduleName),
+     *   findByName(scheduleName), findDue(now)
+     * @param {Object} [options.queueProvider] - Queue provider for dispatching due jobs
+     */
+    constructor(options = {}) {
+        super();
+        this.repository = options.repository;
+        this.queueProvider = options.queueProvider;
+
+        if (!this.repository) {
+            console.warn(
+                '[NetlifyScheduler] No repository provided. ' +
+                    'Schedules will be stored in memory (lost on function restart). ' +
+                    'Provide a database-backed repository for production use.'
+            );
+            this._inMemorySchedules = new Map();
+        }
+    }
+
+    async scheduleOneTime({
+        scheduleName,
+        scheduleAt,
+        queueResourceId,
+        payload,
+    }) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+        if (!scheduleAt || !(scheduleAt instanceof Date))
+            throw new Error('scheduleAt must be a valid Date object');
+        if (!queueResourceId) throw new Error('queueResourceId is required');
+
+        const scheduleData = {
+            scheduleName,
+            scheduledAt: scheduleAt.toISOString(),
+            queueResourceId,
+            payload,
+            createdAt: new Date().toISOString(),
+            state: 'PENDING',
+        };
+
+        if (this.repository) {
+            await this.repository.save(scheduleData);
+        } else {
+            this._inMemorySchedules.set(scheduleName, scheduleData);
+        }
+
+        console.log(
+            `[NetlifyScheduler] Scheduled: ${scheduleName} for ${scheduleAt.toISOString()}`
+        );
+
+        return {
+            scheduledJobId: `netlify-schedule-${scheduleName}`,
+            scheduledAt: scheduleAt.toISOString(),
+        };
+    }
+
+    async deleteSchedule(scheduleName) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+
+        if (this.repository) {
+            await this.repository.delete(scheduleName);
+        } else {
+            this._inMemorySchedules.delete(scheduleName);
+        }
+
+        console.log(`[NetlifyScheduler] Deleted schedule: ${scheduleName}`);
+    }
+
+    async getScheduleStatus(scheduleName) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+
+        let schedule;
+        if (this.repository) {
+            schedule = await this.repository.findByName(scheduleName);
+        } else {
+            schedule = this._inMemorySchedules.get(scheduleName);
+        }
+
+        if (!schedule) {
+            return { exists: false };
+        }
+
+        return {
+            exists: true,
+            scheduledAt: schedule.scheduledAt,
+            state: schedule.state,
+        };
+    }
+
+    /**
+     * Process due schedules. Called by the Netlify cron function.
+     *
+     * Finds all schedules where scheduledAt <= now, dispatches them
+     * to the queue provider, and marks them as completed.
+     *
+     * @returns {Promise<{ processed: number, errors: number }>}
+     */
+    async processDueSchedules() {
+        if (!this.repository) {
+            console.warn(
+                '[NetlifyScheduler] Cannot process due schedules without a repository'
+            );
+            return { processed: 0, errors: 0 };
+        }
+
+        const now = new Date();
+        const dueSchedules = await this.repository.findDue(now);
+
+        let processed = 0;
+        let errors = 0;
+
+        for (const schedule of dueSchedules) {
+            try {
+                if (this.queueProvider) {
+                    await this.queueProvider.send(
+                        schedule.payload,
+                        schedule.queueResourceId
+                    );
+                } else {
+                    console.log(
+                        `[NetlifyScheduler] No queue provider — logging payload for: ${schedule.scheduleName}`,
+                        JSON.stringify(schedule.payload)
+                    );
+                }
+
+                await this.repository.delete(schedule.scheduleName);
+                processed++;
+            } catch (error) {
+                console.error(
+                    `[NetlifyScheduler] Error processing schedule ${schedule.scheduleName}:`,
+                    error
+                );
+                errors++;
+            }
+        }
+
+        console.log(
+            `[NetlifyScheduler] Processed ${processed} due schedules, ${errors} errors`
+        );
+        return { processed, errors };
+    }
+}
+
+module.exports = { NetlifySchedulerAdapter };

packages/core/infrastructure/scheduler/scheduler-service-factory.js

@@ -13,10 +13,12 @@
 
 const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
 const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
+const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
 
 const SCHEDULER_PROVIDERS = {
     EVENTBRIDGE: 'eventbridge',
     MOCK: 'mock',
+    NETLIFY: 'netlify',
 };
 
 const LOCAL_STAGES = ['dev', 'test', 'local'];
@@ -44,9 +46,11 @@ function determineProvider() {
  * Create a scheduler service instance
  *
  * @param {Object} options
- * @param {string} options.provider - Scheduler provider ('eventbridge' or 'mock')
+ * @param {string} options.provider - Scheduler provider ('eventbridge', 'mock', or 'netlify')
  * @param {string} options.region - AWS region (for EventBridge)
  * @param {boolean} options.verbose - Verbose logging (for Mock)
+ * @param {Object} options.repository - Schedule repository (for Netlify - persists schedules)
+ * @param {Object} options.queueProvider - Queue provider (for Netlify - dispatches due jobs)
  * @returns {SchedulerServiceInterface} Implementation of scheduler interface
  */
 function createSchedulerService(options = {}) {
@@ -61,6 +65,11 @@ function createSchedulerService(options = {}) {
             return new MockSchedulerAdapter({
                 verbose: options.verbose,
             });
+        case SCHEDULER_PROVIDERS.NETLIFY:
+            return new NetlifySchedulerAdapter({
+                repository: options.repository,
+                queueProvider: options.queueProvider,
+            });
         default:
             throw new Error(`Unknown scheduler provider: ${provider}`);
     }

packages/core/prisma-mongodb/schema.prisma

@@ -429,3 +429,21 @@ model ScriptSchedule {
   @@index([enabled])
   @@map("ScriptSchedule")
 }
+
+/// One-time scheduled jobs for poll-and-dispatch scheduling pattern.
+/// Used by providers without native one-time scheduling APIs (e.g., Netlify).
+/// A cron function queries for due jobs and dispatches them to a queue.
+model ScheduledJob {
+  id              String   @id @default(auto()) @map("_id") @db.ObjectId
+  scheduleName    String   @unique
+  scheduledAt     DateTime
+  queueResourceId String
+  payload         Json?
+  state           String   @default("PENDING")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([state, scheduledAt])
+  @@map("ScheduledJob")
+}

packages/core/prisma-postgresql/schema.prisma

@@ -411,3 +411,20 @@ model ScriptSchedule {
 
   @@index([enabled])
 }
+
+/// One-time scheduled jobs for poll-and-dispatch scheduling pattern.
+/// Used by providers without native one-time scheduling APIs (e.g., Netlify).
+/// A cron function queries for due jobs and dispatches them to a queue.
+model ScheduledJob {
+  id              Int       @id @default(autoincrement())
+  scheduleName    String    @unique
+  scheduledAt     DateTime
+  queueResourceId String
+  payload         Json?
+  state           String    @default("PENDING")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([state, scheduledAt])
+}

packages/core/providers/index.js

@@ -0,0 +1,13 @@
+const {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+} = require('./resolve-provider');
+
+module.exports = {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+};