reqon-dsl 0.2.0 → 0.4.0

package/dist/pause/store.js

@@ -0,0 +1,158 @@
+/**
+ * Pause Store - Persistence for pause states
+ *
+ * Stores pause state for resource-free long pauses,
+ * enabling resumption after extended periods.
+ */
+import { safeJoin } from '../utils/path.js';
+import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, } from '../utils/file.js';
+/**
+ * File-based pause store
+ */
+export class FilePauseStore {
+    baseDir;
+    initialized;
+    constructor(baseDir = '.reqon-data/pauses') {
+        this.baseDir = baseDir;
+        this.initialized = ensureDirectory(this.baseDir);
+    }
+    getFilePath(id) {
+        return safeJoin(this.baseDir, `${id}.json`);
+    }
+    deserialize(parsed) {
+        restoreDates(parsed, ['pausedAt', 'expiresAt', 'resumedAt']);
+        return parsed;
+    }
+    async save(pause) {
+        await this.initialized;
+        // Pause files hold the captured variables needed to resume (so they can't
+        // be redacted); write owner-only (0o600) so they aren't world-readable.
+        await writeJsonFile(this.getFilePath(pause.id), pause, true, 0o600);
+    }
+    async load(id) {
+        await this.initialized;
+        const parsed = await readJsonFile(this.getFilePath(id));
+        return parsed ? this.deserialize(parsed) : null;
+    }
+    async loadByExecution(executionId) {
+        const all = await this.listActive();
+        return all.find((p) => p.executionId === executionId) ?? null;
+    }
+    async listActive() {
+        await this.initialized;
+        const files = await listFiles(this.baseDir, '.json');
+        const pauses = [];
+        for (const file of files) {
+            const parsed = await readJsonFile(file);
+            if (parsed) {
+                const pause = this.deserialize(parsed);
+                if (pause.status === 'waiting') {
+                    pauses.push(pause);
+                }
+            }
+        }
+        return pauses.sort((a, b) => a.expiresAt.getTime() - b.expiresAt.getTime());
+    }
+    async listByMission(mission) {
+        await this.initialized;
+        const files = await listFiles(this.baseDir, '.json');
+        const pauses = [];
+        for (const file of files) {
+            const parsed = await readJsonFile(file);
+            if (parsed) {
+                const pause = this.deserialize(parsed);
+                if (pause.mission === mission) {
+                    pauses.push(pause);
+                }
+            }
+        }
+        return pauses.sort((a, b) => b.pausedAt.getTime() - a.pausedAt.getTime());
+    }
+    async delete(id) {
+        await this.initialized;
+        await deleteFile(this.getFilePath(id));
+    }
+    async findExpired() {
+        const active = await this.listActive();
+        const now = new Date();
+        return active.filter((p) => p.expiresAt <= now);
+    }
+    async update(id, updates) {
+        const pause = await this.load(id);
+        if (!pause) {
+            throw new Error(`Pause not found: ${id}`);
+        }
+        const updated = { ...pause, ...updates };
+        await this.save(updated);
+    }
+}
+/**
+ * In-memory pause store (for testing)
+ */
+export class MemoryPauseStore {
+    pauses = new Map();
+    async save(pause) {
+        this.pauses.set(pause.id, JSON.parse(JSON.stringify(pause)));
+    }
+    async load(id) {
+        const pause = this.pauses.get(id);
+        if (!pause)
+            return null;
+        const restored = JSON.parse(JSON.stringify(pause));
+        restored.pausedAt = new Date(restored.pausedAt);
+        restored.expiresAt = new Date(restored.expiresAt);
+        if (restored.resumedAt) {
+            restored.resumedAt = new Date(restored.resumedAt);
+        }
+        return restored;
+    }
+    async loadByExecution(executionId) {
+        for (const pause of this.pauses.values()) {
+            if (pause.executionId === executionId && pause.status === 'waiting') {
+                return this.load(pause.id);
+            }
+        }
+        return null;
+    }
+    async listActive() {
+        const pauses = [];
+        for (const pause of this.pauses.values()) {
+            if (pause.status === 'waiting') {
+                const loaded = await this.load(pause.id);
+                if (loaded)
+                    pauses.push(loaded);
+            }
+        }
+        return pauses.sort((a, b) => a.expiresAt.getTime() - b.expiresAt.getTime());
+    }
+    async listByMission(mission) {
+        const pauses = [];
+        for (const pause of this.pauses.values()) {
+            if (pause.mission === mission) {
+                const loaded = await this.load(pause.id);
+                if (loaded)
+                    pauses.push(loaded);
+            }
+        }
+        return pauses.sort((a, b) => b.pausedAt.getTime() - a.pausedAt.getTime());
+    }
+    async delete(id) {
+        this.pauses.delete(id);
+    }
+    async findExpired() {
+        const active = await this.listActive();
+        const now = new Date();
+        return active.filter((p) => p.expiresAt <= now);
+    }
+    async update(id, updates) {
+        const pause = await this.load(id);
+        if (!pause) {
+            throw new Error(`Pause not found: ${id}`);
+        }
+        const updated = { ...pause, ...updates };
+        await this.save(updated);
+    }
+    clear() {
+        this.pauses.clear();
+    }
+}

package/dist/plugin.d.ts

@@ -1,16 +1,13 @@
 /**
- * Reqon plugin for Vague.
- *
- * This plugin registers Reqon's keywords and statement parsers with Vague,
- * allowing Vague to parse Reqon syntax when the plugin is registered.
- *
- * Usage:
- *   import { registerPlugin } from 'vague-lang';
- *   import { reqonPlugin } from 'reqon';
- *   registerPlugin(reqonPlugin);
- *
- * Or simply import the plugin module to auto-register:
- *   import 'reqon/plugin';
+ * ---
+ * purpose: Vague plugin - registers Reqon keywords with Vague's lexer
+ * exports:
+ *   - reqonPlugin - plugin object for manual registration
+ *   - registerReqonPlugin, unregisterReqonPlugin - registration helpers
+ * related:
+ *   - ./lexer/tokens.ts - REQON_KEYWORDS map
+ *   - vague-lang - parent DSL framework
+ * ---
  */
 import { type VaguePlugin } from 'vague-lang';
 /**

package/dist/plugin.js

@@ -1,18 +1,15 @@
 /**
- * Reqon plugin for Vague.
- *
- * This plugin registers Reqon's keywords and statement parsers with Vague,
- * allowing Vague to parse Reqon syntax when the plugin is registered.
- *
- * Usage:
- *   import { registerPlugin } from 'vague-lang';
- *   import { reqonPlugin } from 'reqon';
- *   registerPlugin(reqonPlugin);
- *
- * Or simply import the plugin module to auto-register:
- *   import 'reqon/plugin';
+ * ---
+ * purpose: Vague plugin - registers Reqon keywords with Vague's lexer
+ * exports:
+ *   - reqonPlugin - plugin object for manual registration
+ *   - registerReqonPlugin, unregisterReqonPlugin - registration helpers
+ * related:
+ *   - ./lexer/tokens.ts - REQON_KEYWORDS map
+ *   - vague-lang - parent DSL framework
+ * ---
  */
-import { registerPlugin, unregisterPlugin, } from 'vague-lang';
+import { registerPlugin, unregisterPlugin } from 'vague-lang';
 import { REQON_KEYWORDS } from './lexer/tokens.js';
 /**
  * Convert REQON_KEYWORDS map to PluginKeyword array for Vague plugin system.

package/dist/scheduler/cron-parser.d.ts

@@ -3,7 +3,7 @@ import type { ScheduleDefinition, IntervalSchedule } from '../ast/nodes.js';
  * Parse a cron expression and calculate the next run time
  *
  * Cron format: "minute hour day-of-month month day-of-week"
- * Supports: numbers, ranges (1-5), steps (*​/5), lists (1,3,5), and wildcards (*)
+ * Supports: numbers, ranges (1-5), steps (* /5), lists (1,3,5), and wildcards (*)
  */
 export declare function parseCronExpression(expression: string): CronSchedule;
 interface CronSchedule {
@@ -12,11 +12,18 @@ interface CronSchedule {
     dayOfMonth: number[];
     month: number[];
     dayOfWeek: number[];
+    /** True when day-of-month is not `*` (used for POSIX OR matching). */
+    dayOfMonthRestricted: boolean;
+    /** True when day-of-week is not `*` (used for POSIX OR matching). */
+    dayOfWeekRestricted: boolean;
 }
 /**
- * Calculate the next run time for a cron schedule
+ * Calculate the next run time for a cron schedule, evaluated against
+ * wall-clock time in `timeZone` (default UTC, so DST never shifts the result).
+ * Day-of-month and day-of-week follow POSIX: when both are restricted the
+ * match is their union (OR), not their intersection.
  */
-export declare function getNextCronRun(schedule: CronSchedule, after?: Date): Date;
+export declare function getNextCronRun(schedule: CronSchedule, after?: Date, timeZone?: string): Date;
 /**
  * Convert interval schedule to milliseconds
  */

package/dist/scheduler/cron-parser.js

@@ -2,7 +2,7 @@
  * Parse a cron expression and calculate the next run time
  *
  * Cron format: "minute hour day-of-month month day-of-week"
- * Supports: numbers, ranges (1-5), steps (*​/5), lists (1,3,5), and wildcards (*)
+ * Supports: numbers, ranges (1-5), steps (* /5), lists (1,3,5), and wildcards (*)
  */
 export function parseCronExpression(expression) {
     const parts = expression.trim().split(/\s+/);
@@ -14,11 +14,29 @@ export function parseCronExpression(expression) {
         hour: parseField(parts[1], 0, 23),
         dayOfMonth: parseField(parts[2], 1, 31),
         month: parseField(parts[3], 1, 12),
-        dayOfWeek: parseField(parts[4], 0, 6), // 0 = Sunday
+        dayOfWeek: parseField(parts[4], 0, 6, true), // 0 = Sunday; 7 also = Sunday
+        // POSIX day matching keys off whether each field is a literal wildcard.
+        dayOfMonthRestricted: parts[2] !== '*',
+        dayOfWeekRestricted: parts[4] !== '*',
     };
 }
-function parseField(field, min, max) {
+/**
+ * Parse one cron field into the explicit set of integers it matches.
+ *
+ * Validation is strict and fails fast (rather than silently yielding an empty
+ * set or, worse, hanging): steps must be integers >= 1, bounds must be numeric,
+ * and ranges must not run backwards. When `allowSundaySeven` is set (day-of-week
+ * only) a literal 7 is accepted and normalised to 0 (Sunday).
+ */
+function parseField(field, min, max, allowSundaySeven = false) {
     const values = new Set();
+    const toInt = (token, label) => {
+        const n = parseInt(token, 10);
+        if (!Number.isInteger(n) || !/^[+-]?\d+$/.test(token.trim())) {
+            throw new Error(`Invalid cron ${label} '${token}' in '${field}': expected an integer`);
+        }
+        return n;
+    };
     for (const part of field.split(',')) {
         if (part === '*') {
             // All values
@@ -30,88 +48,244 @@ function parseField(field, min, max) {
             // Step values (e.g., */5 or 1-10/2)
             const [range, stepStr] = part.split('/');
             const step = parseInt(stepStr, 10);
+            if (!Number.isInteger(step) || step < 1) {
+                throw new Error(`Invalid cron step '${stepStr}' in '${part}': step must be an integer >= 1`);
+            }
             let start = min;
             let end = max;
             if (range !== '*') {
                 if (range.includes('-')) {
-                    const [rangeStart, rangeEnd] = range.split('-').map((n) => parseInt(n, 10));
-                    start = rangeStart;
-                    end = rangeEnd;
+                    const [rangeStart, rangeEnd] = range.split('-');
+                    start = toInt(rangeStart, 'range start');
+                    end = toInt(rangeEnd, 'range end');
                 }
                 else {
-                    start = parseInt(range, 10);
+                    start = toInt(range, 'range start');
                 }
             }
+            if (end < start) {
+                throw new Error(`Invalid cron range '${range}' in '${part}': ${start} is after ${end}`);
+            }
             for (let i = start; i <= end; i += step) {
                 values.add(i);
             }
         }
         else if (part.includes('-')) {
             // Range (e.g., 1-5)
-            const [start, end] = part.split('-').map((n) => parseInt(n, 10));
+            const [startStr, endStr] = part.split('-');
+            const start = toInt(startStr, 'range start');
+            const end = toInt(endStr, 'range end');
+            if (end < start) {
+                throw new Error(`Invalid cron range '${part}': ${start} is after ${end}`);
+            }
             for (let i = start; i <= end; i++) {
                 values.add(i);
             }
         }
         else {
             // Single value
-            values.add(parseInt(part, 10));
+            values.add(toInt(part, 'value'));
         }
     }
-    // Validate all values are in range
+    // Day-of-week 7 is an alias for Sunday (0) in standard cron.
+    const normalized = new Set();
     for (const value of values) {
-        if (value < min || value > max) {
+        normalized.add(allowSundaySeven && value === 7 ? 0 : value);
+    }
+    // Validate all values are in range (NaN is rejected by `toInt` above, but
+    // guard explicitly so an out-of-range NaN can never slip through).
+    for (const value of normalized) {
+        if (Number.isNaN(value) || value < min || value > max) {
             throw new Error(`Cron field value ${value} out of range [${min}, ${max}]`);
         }
     }
-    return Array.from(values).sort((a, b) => a - b);
+    return Array.from(normalized).sort((a, b) => a - b);
+}
+/** Number of days in a given (1-based) month, accounting for leap years. */
+function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+/** The day-of-week (0 = Sunday) for a calendar date — timezone-independent. */
+function weekdayOf(year, month, day) {
+    return new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+}
+/** Read the wall-clock fields of an instant in `timeZone`. */
+function partsInZone(instant, timeZone) {
+    const dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+    });
+    const map = {};
+    for (const part of dtf.formatToParts(new Date(instant))) {
+        if (part.type !== 'literal')
+            map[part.type] = parseInt(part.value, 10);
+    }
+    return {
+        year: map.year,
+        month: map.month,
+        day: map.day,
+        hour: map.hour === 24 ? 0 : map.hour,
+        minute: map.minute,
+    };
+}
+/** Offset (ms) such that wall-clock-in-zone = instant + offset, at `instant`. */
+function zoneOffsetMs(instant, timeZone) {
+    const dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+    });
+    const m = {};
+    for (const part of dtf.formatToParts(new Date(instant))) {
+        if (part.type !== 'literal')
+            m[part.type] = parseInt(part.value, 10);
+    }
+    const hour = m.hour === 24 ? 0 : m.hour;
+    return Date.UTC(m.year, m.month - 1, m.day, hour, m.minute, m.second) - instant;
 }
 /**
- * Calculate the next run time for a cron schedule
+ * Convert a wall-clock time in `timeZone` to the corresponding UTC instant.
+ * Around DST transitions the wall time may be ambiguous or nonexistent; this
+ * resolves to a deterministic nearby instant.
  */
-export function getNextCronRun(schedule, after = new Date()) {
-    const next = new Date(after);
-    next.setSeconds(0, 0);
-    next.setMinutes(next.getMinutes() + 1); // Start from next minute
-    // Try up to 4 years to find a match
+function wallToInstant(wc, timeZone) {
+    const asUTC = Date.UTC(wc.year, wc.month - 1, wc.day, wc.hour, wc.minute);
+    const offset = zoneOffsetMs(asUTC, timeZone);
+    let instant = asUTC - offset;
+    const offset2 = zoneOffsetMs(instant, timeZone);
+    if (offset2 !== offset)
+        instant = asUTC - offset2;
+    return instant;
+}
+/** Advance a wall-clock by one minute, rolling over fields as needed. */
+function addMinute(wc) {
+    let { year, month, day, hour, minute } = wc;
+    minute += 1;
+    if (minute > 59) {
+        minute = 0;
+        hour += 1;
+        if (hour > 23) {
+            hour = 0;
+            day += 1;
+            if (day > daysInMonth(year, month)) {
+                day = 1;
+                month += 1;
+                if (month > 12) {
+                    month = 1;
+                    year += 1;
+                }
+            }
+        }
+    }
+    return { year, month, day, hour, minute };
+}
+/**
+ * Calculate the next run time for a cron schedule, evaluated against
+ * wall-clock time in `timeZone` (default UTC, so DST never shifts the result).
+ * Day-of-month and day-of-week follow POSIX: when both are restricted the
+ * match is their union (OR), not their intersection.
+ */
+export function getNextCronRun(schedule, after = new Date(), timeZone = 'UTC') {
+    // Fail fast on combinations that can never match (e.g. Feb 31) instead of
+    // grinding through a full multi-year minute-by-minute scan before throwing.
+    assertReachableDayMonth(schedule);
+    // Start from the first whole minute strictly after `after`.
+    const wc = addMinute(partsInZone(after.getTime(), timeZone));
     const maxIterations = 4 * 366 * 24 * 60;
     for (let i = 0; i < maxIterations; i++) {
-        // Check month
-        if (!schedule.month.includes(next.getMonth() + 1)) {
-            // Move to first day of next matching month
-            next.setMonth(next.getMonth() + 1);
-            next.setDate(1);
-            next.setHours(0, 0, 0, 0);
+        if (!schedule.month.includes(wc.month)) {
+            wc.month += 1;
+            if (wc.month > 12) {
+                wc.month = 1;
+                wc.year += 1;
+            }
+            wc.day = 1;
+            wc.hour = 0;
+            wc.minute = 0;
             continue;
         }
-        // Check day of month
-        if (!schedule.dayOfMonth.includes(next.getDate())) {
-            next.setDate(next.getDate() + 1);
-            next.setHours(0, 0, 0, 0);
+        if (wc.day > daysInMonth(wc.year, wc.month)) {
+            wc.month += 1;
+            if (wc.month > 12) {
+                wc.month = 1;
+                wc.year += 1;
+            }
+            wc.day = 1;
+            wc.hour = 0;
+            wc.minute = 0;
             continue;
         }
-        // Check day of week
-        if (!schedule.dayOfWeek.includes(next.getDay())) {
-            next.setDate(next.getDate() + 1);
-            next.setHours(0, 0, 0, 0);
+        if (!matchesDay(schedule, wc)) {
+            wc.day += 1;
+            wc.hour = 0;
+            wc.minute = 0;
             continue;
         }
-        // Check hour
-        if (!schedule.hour.includes(next.getHours())) {
-            next.setHours(next.getHours() + 1);
-            next.setMinutes(0, 0, 0);
+        if (!schedule.hour.includes(wc.hour)) {
+            wc.hour += 1;
+            wc.minute = 0;
+            if (wc.hour > 23) {
+                wc.hour = 0;
+                wc.day += 1;
+            }
             continue;
         }
-        // Check minute
-        if (!schedule.minute.includes(next.getMinutes())) {
-            next.setMinutes(next.getMinutes() + 1);
+        if (!schedule.minute.includes(wc.minute)) {
+            wc.minute += 1;
+            if (wc.minute > 59) {
+                wc.minute = 0;
+                wc.hour += 1;
+                if (wc.hour > 23) {
+                    wc.hour = 0;
+                    wc.day += 1;
+                }
+            }
             continue;
         }
-        // Found a match!
-        return next;
+        return new Date(wallToInstant(wc, timeZone));
     }
     throw new Error('Could not find next cron run time within 4 years');
 }
+/** Maximum days any given (1-based) month can have, allowing for leap Februarys. */
+const MAX_DAYS_IN_MONTH = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/**
+ * Throw if a restricted day-of-month can never occur in any allowed month.
+ * Only applies when day-of-week is a wildcard: with a restricted weekday the
+ * POSIX OR means a matching day still occurs every month, so it is reachable.
+ */
+function assertReachableDayMonth(schedule) {
+    if (!schedule.dayOfMonthRestricted || schedule.dayOfWeekRestricted)
+        return;
+    const reachable = schedule.month.some((m) => schedule.dayOfMonth.some((d) => d <= MAX_DAYS_IN_MONTH[m]));
+    if (!reachable) {
+        throw new Error(`Cron schedule can never match: day-of-month [${schedule.dayOfMonth.join(',')}] never occurs in month(s) [${schedule.month.join(',')}]`);
+    }
+}
+/** POSIX day matching: union of day-of-month and day-of-week when both set. */
+function matchesDay(schedule, wc) {
+    const domMatch = schedule.dayOfMonth.includes(wc.day);
+    const dowMatch = schedule.dayOfWeek.includes(weekdayOf(wc.year, wc.month, wc.day));
+    const domR = schedule.dayOfMonthRestricted;
+    const dowR = schedule.dayOfWeekRestricted;
+    if (domR && dowR)
+        return domMatch || dowMatch;
+    if (domR)
+        return domMatch;
+    if (dowR)
+        return dowMatch;
+    return true;
+}
 /**
  * Convert interval schedule to milliseconds
  */
@@ -142,7 +316,7 @@ export function getNextRunTime(schedule, after = new Date()) {
                 throw new Error('Cron schedule missing cron expression');
             }
             const cronSchedule = parseCronExpression(schedule.cronExpression);
-            return getNextCronRun(cronSchedule, after);
+            return getNextCronRun(cronSchedule, after, schedule.timezone ?? 'UTC');
         }
         case 'once': {
             if (!schedule.runAt) {
@@ -178,19 +352,24 @@ export function shouldRunNow(schedule, lastRun, checkIntervalMs = 1000) {
             if (!schedule.cronExpression)
                 return false;
             const cronSchedule = parseCronExpression(schedule.cronExpression);
-            const nextRun = getNextCronRun(cronSchedule, lastRun ?? new Date(0));
-            // Check if we're within the check interval of the next run time
-            const diff = Math.abs(now.getTime() - nextRun.getTime());
-            return diff <= checkIntervalMs;
+            // Drift-free: the job is due once its next scheduled time after the last
+            // run has arrived. A late or slow poll never silently skips a tick — the
+            // overshot run still satisfies `nextRun <= now`, instead of needing `now`
+            // to land within a 1s window of the scheduled time.
+            const baseline = lastRun ?? new Date(now.getTime() - checkIntervalMs);
+            const nextRun = getNextCronRun(cronSchedule, baseline, schedule.timezone ?? 'UTC');
+            return nextRun.getTime() <= now.getTime();
         }
         case 'once': {
             if (!schedule.runAt)
                 return false;
             if (lastRun)
                 return false; // Already ran
+            // Fire as soon as the scheduled instant has arrived. A missed tick must
+            // not strand the job: once runAt is in the past (and it has never run),
+            // the next check still catches it, rather than only a ±checkInterval window.
             const runAt = new Date(schedule.runAt);
-            const diff = Math.abs(now.getTime() - runAt.getTime());
-            return diff <= checkIntervalMs;
+            return now.getTime() >= runAt.getTime();
         }
         default:
             return false;