@renseiai/agentfactory 0.8.7 → 0.8.9

package/dist/src/workflow/gates/timer-gate.js

@@ -0,0 +1,381 @@
+/**
+ * Timer Gate Executor
+ *
+ * Pure-function executor for cron-based timer gates. Evaluates whether a
+ * timer gate's cron schedule has fired, and computes the next fire time.
+ *
+ * Implements a from-scratch 5-field cron parser supporting:
+ * - Exact values: 5, 10
+ * - Wildcards: *
+ * - Ranges: 1-5
+ * - Step values: *\/15, 1-30/5
+ * - Lists: 1,3,5
+ *
+ * No external dependencies are used.
+ */
+// ---------------------------------------------------------------------------
+// Cron Field Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single cron field into a set of valid integer values.
+ *
+ * Supported syntax:
+ * - `*`       — all values in [min, max]
+ * - `5`       — exact value
+ * - `1-5`     — inclusive range
+ * - `*\/15`   — step from min
+ * - `1-30/5`  — step within a range
+ * - `1,3,5`   — list of values (each element can be a range or step)
+ *
+ * @param field - The raw cron field string
+ * @param min   - Minimum valid value for this field (inclusive)
+ * @param max   - Maximum valid value for this field (inclusive)
+ * @returns A sorted array of unique integers that the field expands to
+ * @throws Error if the field contains invalid syntax
+ */
+export function parseCronField(field, min, max) {
+    const result = new Set();
+    const parts = field.split(',');
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed === '') {
+            throw new Error(`Invalid cron field: empty segment in "${field}"`);
+        }
+        // Check for step value (e.g., */15 or 1-30/5)
+        const stepParts = trimmed.split('/');
+        if (stepParts.length > 2) {
+            throw new Error(`Invalid cron field: multiple '/' in "${trimmed}"`);
+        }
+        let rangeStart;
+        let rangeEnd;
+        let step = 1;
+        if (stepParts.length === 2) {
+            step = parseInt(stepParts[1], 10);
+            if (isNaN(step) || step <= 0) {
+                throw new Error(`Invalid cron step value: "${stepParts[1]}" in "${trimmed}"`);
+            }
+        }
+        const base = stepParts[0];
+        if (base === '*') {
+            rangeStart = min;
+            rangeEnd = max;
+        }
+        else if (base.includes('-')) {
+            const rangeParts = base.split('-');
+            if (rangeParts.length !== 2) {
+                throw new Error(`Invalid cron range: "${base}" in "${trimmed}"`);
+            }
+            rangeStart = parseInt(rangeParts[0], 10);
+            rangeEnd = parseInt(rangeParts[1], 10);
+            if (isNaN(rangeStart) || isNaN(rangeEnd)) {
+                throw new Error(`Invalid cron range values: "${base}" in "${trimmed}"`);
+            }
+            if (rangeStart < min || rangeEnd > max || rangeStart > rangeEnd) {
+                throw new Error(`Cron range out of bounds: ${rangeStart}-${rangeEnd} (valid: ${min}-${max})`);
+            }
+        }
+        else {
+            const value = parseInt(base, 10);
+            if (isNaN(value)) {
+                throw new Error(`Invalid cron value: "${base}" in "${trimmed}"`);
+            }
+            if (value < min || value > max) {
+                throw new Error(`Cron value out of bounds: ${value} (valid: ${min}-${max})`);
+            }
+            rangeStart = value;
+            rangeEnd = value;
+        }
+        for (let i = rangeStart; i <= rangeEnd; i += step) {
+            result.add(i);
+        }
+    }
+    return Array.from(result).sort((a, b) => a - b);
+}
+/**
+ * Parse a 5-field cron expression string into structured arrays of valid values.
+ *
+ * @param cronExpression - Standard 5-field cron string (e.g., "0 9 * * 1-5")
+ * @returns Parsed cron with expanded field values
+ * @throws Error if the expression doesn't have exactly 5 fields
+ */
+export function parseCronExpression(cronExpression) {
+    const fields = cronExpression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Invalid cron expression: expected 5 fields, got ${fields.length} in "${cronExpression}"`);
+    }
+    return {
+        minutes: parseCronField(fields[0], 0, 59),
+        hours: parseCronField(fields[1], 0, 23),
+        daysOfMonth: parseCronField(fields[2], 1, 31),
+        months: parseCronField(fields[3], 1, 12),
+        // Day of week: 0-7 where both 0 and 7 mean Sunday
+        daysOfWeek: normalizeDaysOfWeek(parseCronField(fields[4], 0, 7)),
+    };
+}
+/**
+ * Normalize day-of-week values so that 7 (Sunday) maps to 0.
+ * Returns a deduplicated sorted array.
+ */
+function normalizeDaysOfWeek(days) {
+    const normalized = new Set();
+    for (const d of days) {
+        normalized.add(d === 7 ? 0 : d);
+    }
+    return Array.from(normalized).sort((a, b) => a - b);
+}
+// ---------------------------------------------------------------------------
+// Next Cron Fire Time Computation
+// ---------------------------------------------------------------------------
+/**
+ * Compute the next cron fire time strictly after a given timestamp.
+ *
+ * Algorithm:
+ * 1. Start from the minute after the `after` timestamp
+ * 2. Check month, day-of-month, day-of-week, hour, minute in sequence
+ * 3. If a field doesn't match, advance to the next valid value and reset
+ *    all lower-order fields
+ * 4. Guard against infinite loops with a maximum iteration count
+ *
+ * @param cronExpression - Standard 5-field cron expression
+ * @param after - Epoch milliseconds; the next fire time is strictly after this
+ * @returns Epoch milliseconds of the next matching cron time
+ * @throws Error if no valid fire time is found within the search window
+ */
+export function computeNextCronFireTime(cronExpression, after) {
+    const cron = parseCronExpression(cronExpression);
+    // Start from one minute after the given timestamp, zeroing out seconds/ms
+    const start = new Date(after);
+    start.setSeconds(0, 0);
+    start.setMinutes(start.getMinutes() + 1);
+    let year = start.getFullYear();
+    let month = start.getMonth() + 1; // 1-based
+    let day = start.getDate();
+    let hour = start.getHours();
+    let minute = start.getMinutes();
+    // Safety limit to prevent infinite loops (4 years of minutes should be plenty)
+    const MAX_ITERATIONS = 4 * 366 * 24 * 60;
+    for (let i = 0; i < MAX_ITERATIONS; i++) {
+        // --- Month ---
+        if (!cron.months.includes(month)) {
+            const nextMonth = findNextValue(cron.months, month);
+            if (nextMonth === null || nextMonth < month) {
+                // Wrap to next year
+                year++;
+                month = cron.months[0];
+            }
+            else {
+                month = nextMonth;
+            }
+            day = 1;
+            hour = 0;
+            minute = 0;
+        }
+        // --- Day of month ---
+        const maxDay = daysInMonth(year, month);
+        // Filter valid days for the actual month length
+        const validDays = cron.daysOfMonth.filter(d => d <= maxDay);
+        if (validDays.length === 0) {
+            // No valid day in this month; advance to next month
+            month++;
+            if (month > 12) {
+                month = 1;
+                year++;
+            }
+            day = 1;
+            hour = 0;
+            minute = 0;
+            continue;
+        }
+        if (!validDays.includes(day)) {
+            const nextDay = findNextValue(validDays, day);
+            if (nextDay === null || nextDay < day) {
+                // Wrap to next month
+                month++;
+                if (month > 12) {
+                    month = 1;
+                    year++;
+                }
+                day = 1;
+                hour = 0;
+                minute = 0;
+                continue;
+            }
+            day = nextDay;
+            hour = 0;
+            minute = 0;
+        }
+        // --- Day of week ---
+        const candidateDate = new Date(year, month - 1, day);
+        const dow = candidateDate.getDay(); // 0=Sunday
+        if (!cron.daysOfWeek.includes(dow)) {
+            // Advance to the next day
+            day++;
+            if (day > maxDay) {
+                month++;
+                if (month > 12) {
+                    month = 1;
+                    year++;
+                }
+                day = 1;
+            }
+            hour = 0;
+            minute = 0;
+            continue;
+        }
+        // --- Hour ---
+        if (!cron.hours.includes(hour)) {
+            const nextHour = findNextValue(cron.hours, hour);
+            if (nextHour === null || nextHour < hour) {
+                // Wrap to next day
+                day++;
+                if (day > maxDay) {
+                    month++;
+                    if (month > 12) {
+                        month = 1;
+                        year++;
+                    }
+                    day = 1;
+                }
+                hour = 0;
+                minute = 0;
+                continue;
+            }
+            hour = nextHour;
+            minute = 0;
+        }
+        // --- Minute ---
+        if (!cron.minutes.includes(minute)) {
+            const nextMinute = findNextValue(cron.minutes, minute);
+            if (nextMinute === null || nextMinute < minute) {
+                // Wrap to next hour
+                hour++;
+                if (hour > 23) {
+                    day++;
+                    if (day > maxDay) {
+                        month++;
+                        if (month > 12) {
+                            month = 1;
+                            year++;
+                        }
+                        day = 1;
+                    }
+                    hour = 0;
+                }
+                minute = 0;
+                continue;
+            }
+            minute = nextMinute;
+        }
+        // All fields match! Build the result date.
+        const result = new Date(year, month - 1, day, hour, minute, 0, 0);
+        return result.getTime();
+    }
+    throw new Error(`Could not find next cron fire time for "${cronExpression}" after ${new Date(after).toISOString()} within search window`);
+}
+/**
+ * Find the next value >= target in a sorted array of integers.
+ * Returns null if no such value exists.
+ */
+function findNextValue(sortedValues, target) {
+    for (const v of sortedValues) {
+        if (v >= target)
+            return v;
+    }
+    return null;
+}
+/**
+ * Get the number of days in a given month (1-based) for a given year.
+ * Accounts for leap years.
+ */
+function daysInMonth(year, month) {
+    // Day 0 of the next month gives the last day of the current month
+    return new Date(year, month, 0).getDate();
+}
+// ---------------------------------------------------------------------------
+// Type Guard
+// ---------------------------------------------------------------------------
+/**
+ * Type guard that validates whether a trigger object has the shape
+ * expected for a timer gate (i.e., contains a `cron` string property).
+ *
+ * @param trigger - The trigger record to validate
+ * @returns True if the trigger is a valid TimerGateTrigger
+ */
+export function isTimerGateTrigger(trigger) {
+    return (typeof trigger === 'object' &&
+        trigger !== null &&
+        'cron' in trigger &&
+        typeof trigger.cron === 'string' &&
+        trigger.cron.trim().length > 0);
+}
+// ---------------------------------------------------------------------------
+// Gate Evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate whether a cron-based timer gate should fire.
+ *
+ * This is a pure function (no I/O). It parses the gate's `trigger.cron`
+ * expression, computes the next fire time from the gate's activation time
+ * (or from epoch 0 if no activation context), and checks whether the
+ * current time has reached or passed that fire time.
+ *
+ * @param gate - The gate definition with type "timer" and a trigger containing a cron field
+ * @param now  - Current time in epoch milliseconds (defaults to Date.now() for testability)
+ * @returns TimerGateResult with fired status and next fire time
+ * @throws Error if the gate is not a timer gate or has an invalid trigger
+ */
+export function evaluateTimerGate(gate, now) {
+    const currentTime = now ?? Date.now();
+    if (gate.type !== 'timer') {
+        throw new Error(`evaluateTimerGate called with non-timer gate: type="${gate.type}"`);
+    }
+    if (!isTimerGateTrigger(gate.trigger)) {
+        throw new Error(`Timer gate "${gate.name}" has invalid trigger: missing or empty "cron" field`);
+    }
+    const cronExpression = gate.trigger.cron;
+    // Compute the next fire time relative to one "cycle" before now,
+    // so we can detect whether we're currently in a fire window.
+    // We look for the next fire time after (now - 60 seconds) to catch
+    // the current minute's match, and compare against the current time.
+    const lookbackTime = currentTime - 60_000;
+    const nextFireTime = computeNextCronFireTime(cronExpression, lookbackTime);
+    // The gate has fired if the next fire time (computed from the lookback)
+    // falls at or before the current time
+    const fired = nextFireTime <= currentTime;
+    // Compute the actual next fire time from the current moment for the result
+    const upcomingFireTime = fired
+        ? computeNextCronFireTime(cronExpression, currentTime)
+        : nextFireTime;
+    return {
+        fired,
+        nextFireTime: upcomingFireTime,
+    };
+}
+// ---------------------------------------------------------------------------
+// Gate Filtering
+// ---------------------------------------------------------------------------
+/**
+ * Get all timer gates from a workflow definition that apply to a given phase.
+ *
+ * A gate applies to a phase if:
+ * - The gate's `appliesTo` array includes the phase name, OR
+ * - The gate has no `appliesTo` array (applies to all phases)
+ *
+ * Only gates with `type: "timer"` are returned.
+ *
+ * @param workflow - The workflow definition to search
+ * @param phase   - The phase name to filter by
+ * @returns Array of GateDefinition objects for matching timer gates
+ */
+export function getApplicableTimerGates(workflow, phase) {
+    if (!workflow.gates) {
+        return [];
+    }
+    return workflow.gates.filter(gate => {
+        if (gate.type !== 'timer')
+            return false;
+        if (!gate.appliesTo || gate.appliesTo.length === 0)
+            return true;
+        return gate.appliesTo.includes(phase);
+    });
+}

package/dist/src/workflow/gates/timer-gate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timer-gate.test.d.ts.map

package/dist/src/workflow/gates/timer-gate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-gate.test.d.ts","sourceRoot":"","sources":["../../../../src/workflow/gates/timer-gate.test.ts"],"names":[],"mappings":""}

package/dist/src/workflow/gates/timer-gate.test.js

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { parseCronField, parseCronExpression, computeNextCronFireTime, evaluateTimerGate, getApplicableTimerGates, } from './timer-gate.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeGateDefinition(overrides = {}) {
+    return {
+        name: 'test-gate',
+        type: 'timer',
+        trigger: { cron: '0 9 * * *' },
+        ...overrides,
+    };
+}
+function makeWorkflow(gates = []) {
+    return {
+        apiVersion: 'v1.1',
+        kind: 'WorkflowDefinition',
+        metadata: { name: 'test-workflow' },
+        phases: [{ name: 'development', template: 'dev' }],
+        transitions: [{ from: 'Backlog', to: 'development' }],
+        gates,
+    };
+}
+// ---------------------------------------------------------------------------
+// parseCronField
+// ---------------------------------------------------------------------------
+describe('parseCronField', () => {
+    it('parses wildcard (*)', () => {
+        const result = parseCronField('*', 0, 5);
+        expect(result).toEqual([0, 1, 2, 3, 4, 5]);
+    });
+    it('parses exact value', () => {
+        const result = parseCronField('5', 0, 59);
+        expect(result).toEqual([5]);
+    });
+    it('parses range (1-5)', () => {
+        const result = parseCronField('1-5', 0, 59);
+        expect(result).toEqual([1, 2, 3, 4, 5]);
+    });
+    it('parses step value (*/15)', () => {
+        const result = parseCronField('*/15', 0, 59);
+        expect(result).toEqual([0, 15, 30, 45]);
+    });
+    it('parses step within range (1-30/5)', () => {
+        const result = parseCronField('1-30/5', 0, 59);
+        expect(result).toEqual([1, 6, 11, 16, 21, 26]);
+    });
+    it('parses list (1,3,5)', () => {
+        const result = parseCronField('1,3,5', 0, 59);
+        expect(result).toEqual([1, 3, 5]);
+    });
+    it('throws for out-of-bounds value', () => {
+        expect(() => parseCronField('60', 0, 59)).toThrow('out of bounds');
+    });
+    it('throws for out-of-bounds range', () => {
+        expect(() => parseCronField('0-60', 0, 59)).toThrow('out of bounds');
+    });
+    it('throws for invalid value', () => {
+        expect(() => parseCronField('abc', 0, 59)).toThrow('Invalid cron value');
+    });
+    it('throws for empty segment in list', () => {
+        expect(() => parseCronField('1,,3', 0, 59)).toThrow('empty segment');
+    });
+    it('throws for multiple slashes', () => {
+        expect(() => parseCronField('*/5/2', 0, 59)).toThrow("multiple '/'");
+    });
+});
+// ---------------------------------------------------------------------------
+// parseCronExpression
+// ---------------------------------------------------------------------------
+describe('parseCronExpression', () => {
+    it('parses valid 5-field cron expression', () => {
+        const result = parseCronExpression('0 9 * * *');
+        expect(result.minutes).toEqual([0]);
+        expect(result.hours).toEqual([9]);
+        expect(result.daysOfMonth).toHaveLength(31);
+        expect(result.months).toHaveLength(12);
+        expect(result.daysOfWeek).toHaveLength(7);
+    });
+    it('throws for invalid field count (3 fields)', () => {
+        expect(() => parseCronExpression('0 9 *')).toThrow('expected 5 fields');
+    });
+    it('throws for invalid field count (6 fields)', () => {
+        expect(() => parseCronExpression('0 9 * * * *')).toThrow('expected 5 fields');
+    });
+    it('normalizes day-of-week 7 to 0 (Sunday)', () => {
+        const result = parseCronExpression('0 0 * * 7');
+        expect(result.daysOfWeek).toContain(0);
+        expect(result.daysOfWeek).not.toContain(7);
+    });
+    it('deduplicates when both 0 and 7 are present', () => {
+        const result = parseCronExpression('0 0 * * 0,7');
+        expect(result.daysOfWeek).toEqual([0]);
+    });
+});
+// ---------------------------------------------------------------------------
+// computeNextCronFireTime
+// ---------------------------------------------------------------------------
+describe('computeNextCronFireTime', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('computes next fire time for "0 9 * * *" (daily at 9am)', () => {
+        // Set time to June 1, 2025, 08:00 UTC
+        const baseTime = new Date('2025-06-01T08:00:00Z').getTime();
+        const nextFire = computeNextCronFireTime('0 9 * * *', baseTime);
+        const fireDate = new Date(nextFire);
+        // Should fire at 9:00 on the same day (local time)
+        expect(fireDate.getHours()).toBe(9);
+        expect(fireDate.getMinutes()).toBe(0);
+    });
+    it('computes next fire time for weekday-only "0 9 * * 1-5"', () => {
+        // June 1, 2025 is a Sunday (day 0)
+        // Set to Sunday 10:00 — next weekday 9:00 should be Monday
+        const sunday = new Date(2025, 5, 1, 10, 0, 0, 0); // June 1, 2025, Sunday
+        vi.setSystemTime(sunday);
+        const nextFire = computeNextCronFireTime('0 9 * * 1-5', sunday.getTime());
+        const fireDate = new Date(nextFire);
+        // Next valid fire should be Monday (day 1) at 9:00
+        expect(fireDate.getDay()).toBeGreaterThanOrEqual(1);
+        expect(fireDate.getDay()).toBeLessThanOrEqual(5);
+        expect(fireDate.getHours()).toBe(9);
+        expect(fireDate.getMinutes()).toBe(0);
+    });
+    it('computes next fire time for "*/15 * * * *" (every 15 minutes)', () => {
+        const baseTime = new Date(2025, 5, 1, 10, 3, 0, 0).getTime(); // 10:03
+        const nextFire = computeNextCronFireTime('*/15 * * * *', baseTime);
+        const fireDate = new Date(nextFire);
+        // Next 15-minute mark after 10:03 should be 10:15
+        expect(fireDate.getMinutes()).toBe(15);
+        expect(fireDate.getHours()).toBe(10);
+    });
+    it('returns a time strictly after the given timestamp', () => {
+        const baseTime = new Date(2025, 5, 1, 9, 0, 0, 0).getTime(); // exactly 9:00
+        const nextFire = computeNextCronFireTime('0 9 * * *', baseTime);
+        expect(nextFire).toBeGreaterThan(baseTime);
+    });
+});
+// ---------------------------------------------------------------------------
+// evaluateTimerGate
+// ---------------------------------------------------------------------------
+describe('evaluateTimerGate', () => {
+    it('fires when the current time matches the cron schedule', () => {
+        // Set now to 9:00, and use a cron that fires at 9:00 every day
+        const now = new Date(2025, 5, 1, 9, 0, 30, 0).getTime(); // 9:00:30
+        const gate = makeGateDefinition({ trigger: { cron: '0 9 * * *' } });
+        const result = evaluateTimerGate(gate, now);
+        expect(result.fired).toBe(true);
+    });
+    it('does not fire before the scheduled time', () => {
+        const now = new Date(2025, 5, 1, 8, 30, 0, 0).getTime(); // 8:30
+        const gate = makeGateDefinition({ trigger: { cron: '0 9 * * *' } });
+        const result = evaluateTimerGate(gate, now);
+        expect(result.fired).toBe(false);
+    });
+    it('throws for non-timer gate', () => {
+        const gate = makeGateDefinition({ type: 'signal' });
+        expect(() => evaluateTimerGate(gate)).toThrow('non-timer gate');
+    });
+    it('throws for timer gate with missing cron field', () => {
+        const gate = makeGateDefinition({ trigger: {} });
+        expect(() => evaluateTimerGate(gate)).toThrow('missing or empty "cron" field');
+    });
+    it('returns a nextFireTime property', () => {
+        const now = new Date(2025, 5, 1, 8, 30, 0, 0).getTime();
+        const gate = makeGateDefinition({ trigger: { cron: '0 9 * * *' } });
+        const result = evaluateTimerGate(gate, now);
+        expect(result.nextFireTime).toBeGreaterThan(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// getApplicableTimerGates
+// ---------------------------------------------------------------------------
+describe('getApplicableTimerGates', () => {
+    it('filters by type=timer and appliesTo', () => {
+        const gates = [
+            makeGateDefinition({ name: 'timer-1', type: 'timer', appliesTo: ['development'] }),
+            makeGateDefinition({ name: 'signal-1', type: 'signal', appliesTo: ['development'] }),
+            makeGateDefinition({ name: 'timer-2', type: 'timer', appliesTo: ['qa'] }),
+        ];
+        const workflow = makeWorkflow(gates);
+        const result = getApplicableTimerGates(workflow, 'development');
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe('timer-1');
+    });
+    it('returns gates with no appliesTo restriction', () => {
+        const gates = [
+            makeGateDefinition({ name: 'global-timer', type: 'timer' }),
+        ];
+        const workflow = makeWorkflow(gates);
+        const result = getApplicableTimerGates(workflow, 'any-phase');
+        expect(result).toHaveLength(1);
+    });
+    it('returns empty array when no gates defined', () => {
+        const workflow = makeWorkflow();
+        delete workflow.gates;
+        const result = getApplicableTimerGates(workflow, 'development');
+        expect(result).toEqual([]);
+    });
+    it('returns empty array when no timer gates match phase', () => {
+        const gates = [
+            makeGateDefinition({ name: 'timer-qa', type: 'timer', appliesTo: ['qa'] }),
+        ];
+        const workflow = makeWorkflow(gates);
+        const result = getApplicableTimerGates(workflow, 'development');
+        expect(result).toEqual([]);
+    });
+});