crewly 1.5.18 → 1.5.19

package/dist/backend/backend/src/services/v3/trigger-engine.service.d.ts

@@ -0,0 +1,263 @@
+/**
+ * TriggerEngine Service — Manages trigger lifecycle and execution.
+ *
+ * Handles three trigger types:
+ * - TimeTriggers: cron-based or one-shot delay/fireAt scheduling
+ * - SignalTriggers: EventBus event subscriptions with optional filters
+ * - CompoundTriggers: AND/OR combinations of time+signal conditions
+ *
+ * Lifecycle management:
+ * - Tracks fireCount, maxFires (auto-exhaust), maxIdleFires (auto-cancel on idle)
+ * - Persists triggers to disk as JSON
+ * - Supports pause/resume/cancel operations
+ *
+ * @module services/v3/trigger-engine.service
+ */
+import { type Trigger, type TriggerStatus, type TriggerAction, type CreateTriggerInput } from '../../types/v2/index.js';
+import type { EventBusService } from '../event-bus/event-bus.service.js';
+/**
+ * Callback invoked when a trigger fires and produces an action.
+ *
+ * @param trigger - The trigger that fired
+ * @param action - The action to execute
+ */
+export type TriggerActionHandler = (trigger: Trigger, action: TriggerAction) => Promise<void>;
+/**
+ * Result of a trigger fire attempt — indicates whether the fire was productive.
+ */
+export interface TriggerFireResult {
+    /** The trigger that fired */
+    triggerId: string;
+    /** Whether the fire produced useful work (false = idle fire) */
+    productive: boolean;
+    /** ISO timestamp of the fire */
+    firedAt: string;
+}
+/**
+ * TriggerEngine manages the lifecycle of Trigger entities.
+ *
+ * Uses singleton pattern. Time triggers are evaluated on a polling interval.
+ * Signal triggers subscribe to EventBus events. Compound triggers combine
+ * both with AND/OR logic.
+ *
+ * @example
+ * ```typescript
+ * const engine = TriggerEngine.getInstance('/path/to/project');
+ * engine.setEventBus(eventBusService);
+ * engine.setActionHandler(async (trigger, action) => { ... });
+ * await engine.start();
+ * ```
+ */
+export declare class TriggerEngine {
+    private readonly projectPath;
+    private static instance;
+    private readonly logger;
+    private readonly triggersDir;
+    private readonly triggersFile;
+    /** In-memory trigger store, keyed by trigger ID. */
+    private triggers;
+    /** EventBus reference for signal triggers. */
+    private eventBus;
+    /** Callback for executing trigger actions. */
+    private actionHandler;
+    /** Interval handle for time trigger polling. */
+    private timeCheckInterval;
+    /** Timeout handles for one-shot delay/fireAt triggers, keyed by trigger ID. */
+    private oneShotTimers;
+    /** Whether the engine is currently running. */
+    private running;
+    /**
+     * Creates a new TriggerEngine.
+     *
+     * @param projectPath - Absolute path to the project root
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns The singleton TriggerEngine instance
+     */
+    static getInstance(projectPath?: string): TriggerEngine;
+    /**
+     * Resets the singleton instance. For test isolation only.
+     */
+    static resetInstance(): void;
+    /**
+     * Sets the EventBus for signal trigger subscriptions.
+     *
+     * @param eventBus - The EventBusService instance
+     */
+    setEventBus(eventBus: EventBusService): void;
+    /**
+     * Sets the handler that executes trigger actions.
+     *
+     * @param handler - Callback invoked when a trigger fires
+     */
+    setActionHandler(handler: TriggerActionHandler): void;
+    /**
+     * Starts the TriggerEngine: loads persisted triggers from disk,
+     * sets up time polling interval, and registers signal listeners.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the TriggerEngine: clears intervals, timers, and signal listeners.
+     */
+    stop(): void;
+    /**
+     * Returns whether the engine is currently running.
+     *
+     * @returns True if the engine is running
+     */
+    isRunning(): boolean;
+    /**
+     * Creates a new trigger and persists it.
+     *
+     * @param input - Trigger creation input
+     * @returns The created Trigger
+     * @throws Error if input validation fails
+     */
+    create(input: CreateTriggerInput): Promise<Trigger>;
+    /**
+     * Gets a trigger by ID.
+     *
+     * @param id - Trigger UUID
+     * @returns The trigger, or undefined if not found
+     */
+    get(id: string): Trigger | undefined;
+    /**
+     * Lists all triggers, optionally filtered by status.
+     *
+     * @param status - Optional status filter
+     * @returns Array of matching triggers
+     */
+    list(status?: TriggerStatus): Trigger[];
+    /**
+     * Pauses an active trigger.
+     *
+     * @param id - Trigger UUID
+     * @returns True if the trigger was paused
+     */
+    pause(id: string): Promise<boolean>;
+    /**
+     * Resumes a paused trigger.
+     *
+     * @param id - Trigger UUID
+     * @returns True if the trigger was resumed
+     */
+    resume(id: string): Promise<boolean>;
+    /**
+     * Cancels a trigger permanently.
+     *
+     * @param id - Trigger UUID
+     * @returns True if the trigger was cancelled
+     */
+    cancel(id: string): Promise<boolean>;
+    /**
+     * Deletes a trigger entirely (removes from store).
+     *
+     * @param id - Trigger UUID
+     * @returns True if the trigger was deleted
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Fires a trigger: increments counters, executes action, manages lifecycle.
+     *
+     * @param trigger - The trigger to fire
+     * @param productive - Whether this fire is considered productive (not idle)
+     * @returns The fire result
+     */
+    fire(trigger: Trigger, productive?: boolean): Promise<TriggerFireResult>;
+    /**
+     * Sets up the polling interval for cron-based time triggers.
+     */
+    private setupTimePolling;
+    /**
+     * Evaluates all active cron-based time triggers against the current time.
+     */
+    evaluateTimeTriggers(): Promise<TriggerFireResult[]>;
+    /**
+     * Checks if a cron expression matches the current moment.
+     *
+     * @param cronExpression - Standard 5-field cron expression
+     * @param timezone - IANA timezone string
+     * @param now - Current time
+     * @returns True if the cron matches
+     */
+    private cronMatchesNow;
+    /**
+     * Sets up one-shot timers for delay/fireAt time triggers.
+     */
+    private setupOneShotTimers;
+    /**
+     * Schedules a one-shot timer for a delay or fireAt trigger.
+     *
+     * @param trigger - The time trigger to schedule
+     */
+    private scheduleOneShot;
+    /**
+     * Clears a one-shot timer for a trigger.
+     *
+     * @param triggerId - The trigger ID
+     */
+    private clearOneShotTimer;
+    /**
+     * Calculates the next fire time for a time trigger config.
+     *
+     * @param config - Time trigger configuration
+     * @returns ISO string of next fire time, or undefined
+     */
+    private calculateNextFireAt;
+    /**
+     * Sets up EventBus listeners for signal triggers.
+     * Listens to the 'event_published' event on the EventBus.
+     */
+    private setupSignalListeners;
+    /**
+     * Handles an EventBus event by checking all active signal triggers.
+     *
+     * @param eventData - The event data from EventBus
+     */
+    handleSignalEvent(eventData: {
+        eventId: string;
+        eventType: string;
+        sessionName: string;
+    }): Promise<TriggerFireResult[]>;
+    /**
+     * Checks if an event matches a signal trigger's config.
+     *
+     * @param config - Signal trigger configuration
+     * @param eventData - The event data to match against
+     * @returns True if the event matches
+     */
+    private signalMatches;
+    /**
+     * Checks if an event matches a compound trigger's signal conditions.
+     * Only evaluates signal sub-conditions (time conditions are handled separately).
+     *
+     * @param config - Compound trigger configuration
+     * @param eventData - The event data to match against
+     * @returns True if the compound condition is satisfied
+     */
+    private compoundSignalMatches;
+    /**
+     * Loads triggers from disk.
+     */
+    private loadTriggers;
+    /**
+     * Persists all triggers to disk.
+     */
+    private persistTriggers;
+    /**
+     * Returns a summary of trigger engine state.
+     *
+     * @returns Object with counts by status and type
+     */
+    getStatus(): {
+        running: boolean;
+        total: number;
+        byStatus: Record<TriggerStatus, number>;
+        byType: Record<string, number>;
+    };
+}
+//# sourceMappingURL=trigger-engine.service.d.ts.map

package/dist/backend/backend/src/services/v3/trigger-engine.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-engine.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/v3/trigger-engine.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,aAAa,EAKlB,KAAK,kBAAkB,EAKxB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAmBzE;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;IACpB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa;IA8BJ,OAAO,CAAC,QAAQ,CAAC,WAAW;IA7BhD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA8B;IAErD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAmC;IAEnD,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAgC;IAEhD,8CAA8C;IAC9C,OAAO,CAAC,aAAa,CAAqC;IAE1D,gDAAgD;IAChD,OAAO,CAAC,iBAAiB,CAA+C;IAExE,+EAA+E;IAC/E,OAAO,CAAC,aAAa,CAAyD;IAE9E,+CAA+C;IAC/C,OAAO,CAAC,OAAO,CAAS;IAExB;;;;OAIG;IACH,OAAO;IAMP;;;;;OAKG;WACW,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa;IAQ9D;;OAEG;WACW,aAAa,IAAI,IAAI;IAWnC;;;;OAIG;IACI,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAInD;;;;OAIG;IACI,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAQ5D;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAcnC;;OAEG;IACI,IAAI,IAAI,IAAI;IAenB;;;;OAIG;IACI,SAAS,IAAI,OAAO;IAQ3B;;;;;;OAMG;IACU,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BhE;;;;;OAKG;IACI,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI3C;;;;;OAKG;IACI,IAAI,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,EAAE;IAQ9C;;;;;OAKG;IACU,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD;;;;;OAKG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBjD;;;;;OAKG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYjD;;;;;OAKG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAejD;;;;;;OAMG;IACU,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,UAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6DlF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACU,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAuBjE;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAatB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAuCvB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;;;OAIG;IACU,iBAAiB,CAAC,SAAS,EAAE;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsBhC;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAoBrB;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;YACW,YAAY;IAU1B;;OAEG;YACW,eAAe;IAU7B;;;;OAIG;IACI,SAAS,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC;CAqBF"}