@herdctl/core 0.0.1 → 0.1.0

package/dist/scheduler/cron.js

@@ -0,0 +1,390 @@
+/**
+ * Cron expression parsing utilities for the scheduler module
+ *
+ * Parses standard 5-field cron expressions and common shorthands like @daily, @hourly, etc.
+ * Uses the cron-parser library for robust parsing and validation.
+ */
+import cronParser from "cron-parser";
+import { CronParseError, CRON_FIELDS } from "./errors.js";
+/**
+ * Mapping of common cron shorthands to their 5-field equivalents
+ */
+const CRON_SHORTHANDS = {
+    "@yearly": "0 0 1 1 *",
+    "@annually": "0 0 1 1 *",
+    "@monthly": "0 0 1 * *",
+    "@weekly": "0 0 * * 0",
+    "@daily": "0 0 * * *",
+    "@midnight": "0 0 * * *",
+    "@hourly": "0 * * * *",
+};
+/**
+ * Parse a cron expression string into a parsed cron expression object
+ *
+ * Supports standard 5-field cron expressions:
+ * - `minute hour day-of-month month day-of-week`
+ * - Each field supports standard cron syntax (numbers, ranges, lists, steps, *)
+ *
+ * Also supports common shorthands:
+ * - `@yearly` / `@annually` - Run once a year at midnight on January 1st (0 0 1 1 *)
+ * - `@monthly` - Run once a month at midnight on the 1st (0 0 1 * *)
+ * - `@weekly` - Run once a week at midnight on Sunday (0 0 * * 0)
+ * - `@daily` / `@midnight` - Run once a day at midnight (0 0 * * *)
+ * - `@hourly` - Run once an hour at the start of the hour (0 * * * *)
+ *
+ * @param expression - The cron expression to parse
+ * @returns Parsed cron expression with iterator methods
+ * @throws {CronParseError} If the expression is invalid
+ *
+ * @example
+ * // Standard 5-field cron
+ * parseCronExpression("0 9 * * 1-5")  // 9 AM on weekdays
+ * parseCronExpression("0 0 1 * *")    // First of every month
+ *
+ * // Shorthands
+ * parseCronExpression("@daily")       // Midnight every day
+ * parseCronExpression("@hourly")      // Start of every hour
+ * parseCronExpression("@weekly")      // Midnight on Sunday
+ */
+export function parseCronExpression(expression, options) {
+    // Handle empty string
+    if (!expression || expression.trim() === "") {
+        throw new CronParseError('Cron expression cannot be empty. Expected a 5-field cron expression (e.g., "0 9 * * *") or a shorthand like "@daily"', expression);
+    }
+    const trimmed = expression.trim();
+    const isShorthand = trimmed.startsWith("@");
+    // Expand shorthand if applicable
+    let cronExpr = trimmed;
+    if (isShorthand) {
+        const lowerShorthand = trimmed.toLowerCase();
+        const expanded = CRON_SHORTHANDS[lowerShorthand];
+        if (!expanded) {
+            const validShorthands = Object.keys(CRON_SHORTHANDS)
+                .filter((s) => s !== "@annually" && s !== "@midnight") // Don't show aliases
+                .join(", ");
+            throw new CronParseError(`Unknown cron shorthand "${trimmed}". Valid shorthands are: ${validShorthands}`, expression);
+        }
+        cronExpr = expanded;
+    }
+    // Validate field count before parsing
+    const fieldCountError = validateFieldCount(cronExpr);
+    if (fieldCountError) {
+        throw new CronParseError(CronParseError.buildMessage(trimmed, fieldCountError.reason, fieldCountError.example), expression, { field: "fields", example: fieldCountError.example?.expression });
+    }
+    // Check for field-specific validation errors before cron-parser
+    const fieldError = validateCronFields(cronExpr);
+    if (fieldError) {
+        throw new CronParseError(CronParseError.buildMessage(trimmed, fieldError.reason, fieldError.example), expression, { cause: undefined, field: fieldError.field, example: fieldError.example?.expression });
+    }
+    try {
+        const parserOptions = {
+            tz: options?.tz ?? "UTC",
+        };
+        if (options?.currentDate) {
+            parserOptions.currentDate = options.currentDate;
+        }
+        const cronExpression = cronParser.parseExpression(cronExpr, parserOptions);
+        return {
+            expression: cronExpr,
+            cronExpression,
+            isShorthand,
+        };
+    }
+    catch (error) {
+        // Try to extract field-specific error from cron-parser
+        const errorMessage = error instanceof Error ? error.message : "Unknown parsing error";
+        const parsedError = parseErrorMessage(errorMessage, cronExpr);
+        throw new CronParseError(CronParseError.buildMessage(trimmed, parsedError.reason, parsedError.example), expression, {
+            cause: error instanceof Error ? error : undefined,
+            field: parsedError.field,
+            example: parsedError.example?.expression
+        });
+    }
+}
+/**
+ * Validate field count in cron expression
+ */
+function validateFieldCount(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length < 5) {
+        return {
+            reason: `expected 5 fields, got ${fields.length}`,
+            field: "fields",
+            example: { expression: "* * * * *", description: "every minute" },
+        };
+    }
+    if (fields.length > 5) {
+        return {
+            reason: `expected 5 fields, got ${fields.length}`,
+            field: "fields",
+            example: { expression: "0 9 * * *", description: "daily at 9:00 AM" },
+        };
+    }
+    return null;
+}
+/**
+ * Validate individual cron fields for common errors
+ */
+function validateCronFields(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        return null; // Field count validation handles this
+    }
+    for (const fieldInfo of CRON_FIELDS) {
+        const fieldValue = fields[fieldInfo.index];
+        const error = validateField(fieldValue, fieldInfo);
+        if (error) {
+            return error;
+        }
+    }
+    return null;
+}
+/**
+ * Validate a single cron field
+ */
+function validateField(value, fieldInfo) {
+    // Skip wildcards and complex patterns for basic validation
+    if (value === "*") {
+        return null;
+    }
+    // Handle step syntax (e.g., */15)
+    if (value.startsWith("*/")) {
+        const step = parseInt(value.slice(2), 10);
+        if (isNaN(step) || step <= 0) {
+            return {
+                reason: `invalid step value "${value}" for ${fieldInfo.name}`,
+                field: fieldInfo.name,
+                example: getExampleForField(fieldInfo),
+            };
+        }
+        return null;
+    }
+    // Handle ranges (e.g., 1-5)
+    if (value.includes("-") && !value.startsWith("-")) {
+        const parts = value.split("-");
+        if (parts.length === 2) {
+            const start = parseInt(parts[0], 10);
+            const end = parseInt(parts[1], 10);
+            if (!isNaN(start) && !isNaN(end)) {
+                if (start < fieldInfo.min || start > fieldInfo.max) {
+                    return {
+                        reason: `${fieldInfo.name} must be ${fieldInfo.min}-${fieldInfo.max}`,
+                        field: fieldInfo.name,
+                        example: getExampleForField(fieldInfo),
+                    };
+                }
+                if (end < fieldInfo.min || end > fieldInfo.max) {
+                    return {
+                        reason: `${fieldInfo.name} must be ${fieldInfo.min}-${fieldInfo.max}`,
+                        field: fieldInfo.name,
+                        example: getExampleForField(fieldInfo),
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    // Handle lists (e.g., 1,3,5)
+    if (value.includes(",")) {
+        const parts = value.split(",");
+        for (const part of parts) {
+            const num = parseInt(part, 10);
+            if (!isNaN(num) && (num < fieldInfo.min || num > fieldInfo.max)) {
+                return {
+                    reason: `${fieldInfo.name} must be ${fieldInfo.min}-${fieldInfo.max}`,
+                    field: fieldInfo.name,
+                    example: getExampleForField(fieldInfo),
+                };
+            }
+        }
+        return null;
+    }
+    // Handle simple numeric values
+    const num = parseInt(value, 10);
+    if (!isNaN(num)) {
+        if (num < fieldInfo.min || num > fieldInfo.max) {
+            return {
+                reason: `${fieldInfo.name} must be ${fieldInfo.min}-${fieldInfo.max}`,
+                field: fieldInfo.name,
+                example: getExampleForField(fieldInfo),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Get a helpful example for a specific field
+ */
+function getExampleForField(fieldInfo) {
+    switch (fieldInfo.name) {
+        case "minute":
+            return { expression: "30 * * * *", description: "every hour at :30" };
+        case "hour":
+            return { expression: "0 9 * * *", description: "daily at 9:00 AM" };
+        case "day-of-month":
+            return { expression: "0 0 1 * *", description: "first of every month" };
+        case "month":
+            return { expression: "0 0 1 6 *", description: "June 1st at midnight" };
+        case "day-of-week":
+            return { expression: "0 9 * * 1-5", description: "weekdays at 9:00 AM" };
+        default:
+            return { expression: "0 9 * * *", description: "daily at 9:00 AM" };
+    }
+}
+/**
+ * Parse error message from cron-parser and extract field info
+ */
+function parseErrorMessage(errorMessage, expression) {
+    // Try to identify which field failed
+    const lowerMsg = errorMessage.toLowerCase();
+    // Check for "Constraint error" messages from cron-parser
+    if (lowerMsg.includes("constraint error")) {
+        // cron-parser often says things like "Constraint error, got value X expected range Y-Z"
+        const valueMatch = errorMessage.match(/got value (\d+)/i);
+        const rangeMatch = errorMessage.match(/expected range (\d+)-(\d+)/i);
+        if (valueMatch && rangeMatch) {
+            const value = parseInt(valueMatch[1], 10);
+            const min = parseInt(rangeMatch[1], 10);
+            const max = parseInt(rangeMatch[2], 10);
+            // Determine which field based on the range
+            const field = identifyFieldByRange(min, max);
+            if (field) {
+                return {
+                    reason: `${field.name} must be ${field.min}-${field.max}`,
+                    field: field.name,
+                    example: getExampleForField(field),
+                };
+            }
+        }
+    }
+    // Check for field-specific keywords
+    for (const field of CRON_FIELDS) {
+        if (lowerMsg.includes(field.name)) {
+            return {
+                reason: `${field.name} must be ${field.min}-${field.max}`,
+                field: field.name,
+                example: getExampleForField(field),
+            };
+        }
+    }
+    // Generic fallback
+    return {
+        reason: errorMessage,
+        example: { expression: "0 9 * * *", description: "daily at 9:00 AM" },
+    };
+}
+/**
+ * Identify cron field by its valid range
+ */
+function identifyFieldByRange(min, max) {
+    for (const field of CRON_FIELDS) {
+        if (field.min === min && field.max === max) {
+            return field;
+        }
+    }
+    // Handle day-of-week which can be 0-6 or 0-7
+    if (min === 0 && (max === 6 || max === 7)) {
+        return CRON_FIELDS[4]; // day-of-week
+    }
+    return null;
+}
+/**
+ * Get the next trigger time for a cron expression
+ *
+ * @param expression - The cron expression (5-field or shorthand)
+ * @param fromDate - Optional date to calculate from (defaults to now)
+ * @returns The next trigger time as a Date
+ * @throws {CronParseError} If the expression is invalid
+ *
+ * @example
+ * // Get next trigger from now
+ * getNextCronTrigger("0 9 * * 1-5") // Next 9 AM on a weekday
+ *
+ * // Get next trigger from a specific date
+ * getNextCronTrigger("@daily", new Date("2024-01-15T12:00:00Z"))
+ * // Returns 2024-01-16T00:00:00Z
+ */
+export function getNextCronTrigger(expression, fromDate, tz) {
+    const parsed = parseCronExpression(expression, {
+        currentDate: fromDate,
+        tz: tz ?? "UTC",
+    });
+    return parsed.cronExpression.next().toDate();
+}
+/**
+ * Check if a cron expression is valid
+ *
+ * @param expression - The cron expression to validate
+ * @returns true if the expression is valid, false otherwise
+ *
+ * @example
+ * isValidCronExpression("0 9 * * *")  // true
+ * isValidCronExpression("@daily")     // true
+ * isValidCronExpression("invalid")    // false
+ * isValidCronExpression("60 * * * *") // false (minute > 59)
+ */
+export function isValidCronExpression(expression) {
+    try {
+        parseCronExpression(expression);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Calculate the next trigger time for a cron expression using system timezone
+ *
+ * This function uses the system's local timezone for calculations, which is
+ * consistent with interval-based scheduling behavior.
+ *
+ * @param expression - The cron expression (5-field or shorthand)
+ * @param after - Optional date to calculate from (defaults to now)
+ * @returns The next trigger time as a Date
+ * @throws {CronParseError} If the expression is invalid
+ *
+ * @example
+ * // Daily at 9:00 AM
+ * const expr = "0 9 * * *";
+ * const morning = new Date("2024-01-15T08:00:00");
+ * calculateNextCronTrigger(expr, morning)  // Returns 2024-01-15T09:00:00 (local)
+ *
+ * @example
+ * // Every 15 minutes (use step syntax)
+ * const midHour = new Date("2024-01-15T10:07:00");
+ * calculateNextCronTrigger("0,15,30,45 * * * *", midHour)  // Returns 2024-01-15T10:15:00 (local)
+ */
+export function calculateNextCronTrigger(expression, after) {
+    // Get the system timezone
+    const systemTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const parsed = parseCronExpression(expression, {
+        currentDate: after,
+        tz: systemTimezone,
+    });
+    return parsed.cronExpression.next().toDate();
+}
+/**
+ * Calculate the previous trigger time for a cron expression
+ *
+ * Returns the most recent occurrence of the cron schedule before the given time
+ * (or before now if no time is specified).
+ *
+ * @param expression - The cron expression (5-field or shorthand)
+ * @param before - Optional date to calculate from (defaults to now)
+ * @returns The previous trigger time as a Date
+ * @throws {CronParseError} If the expression is invalid
+ *
+ * @example
+ * // If current time is 11:30 and cron is @hourly (at :00)
+ * calculatePreviousCronTrigger("@hourly")  // Returns 11:00
+ */
+export function calculatePreviousCronTrigger(expression, before) {
+    // Get the system timezone
+    const systemTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const parsed = parseCronExpression(expression, {
+        currentDate: before,
+        tz: systemTimezone,
+    });
+    return parsed.cronExpression.prev().toDate();
+}
+//# sourceMappingURL=cron.js.map

package/dist/scheduler/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../../src/scheduler/cron.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/errors.d.ts

@@ -3,12 +3,38 @@
  *
  * Provides typed errors with descriptive messages for scheduler operations.
  */
+import { FleetManagerError } from "../fleet-manager/errors.js";
+/**
+ * Error codes for scheduler errors (extends FleetManagerErrorCode)
+ */
+export declare const SchedulerErrorCode: {
+    readonly CRON_PARSE_ERROR: "CRON_PARSE_ERROR";
+    readonly INTERVAL_PARSE_ERROR: "INTERVAL_PARSE_ERROR";
+    readonly SCHEDULE_TRIGGER_ERROR: "SCHEDULE_TRIGGER_ERROR";
+    readonly SCHEDULER_SHUTDOWN_ERROR: "SCHEDULER_SHUTDOWN_ERROR";
+    readonly FLEET_MANAGER_ERROR: "FLEET_MANAGER_ERROR";
+    readonly CONFIGURATION_ERROR: "CONFIGURATION_ERROR";
+    readonly CONFIG_LOAD_ERROR: "CONFIG_LOAD_ERROR";
+    readonly AGENT_NOT_FOUND: "AGENT_NOT_FOUND";
+    readonly JOB_NOT_FOUND: "JOB_NOT_FOUND";
+    readonly SCHEDULE_NOT_FOUND: "SCHEDULE_NOT_FOUND";
+    readonly INVALID_STATE: "INVALID_STATE";
+    readonly STATE_DIR_ERROR: "STATE_DIR_ERROR";
+    readonly CONCURRENCY_LIMIT: "CONCURRENCY_LIMIT";
+    readonly SHUTDOWN_ERROR: "SHUTDOWN_ERROR";
+    readonly JOB_CANCEL_ERROR: "JOB_CANCEL_ERROR";
+    readonly JOB_FORK_ERROR: "JOB_FORK_ERROR";
+};
+export type SchedulerErrorCode = (typeof SchedulerErrorCode)[keyof typeof SchedulerErrorCode];
 /**
  * Base error class for all scheduler errors
+ *
+ * Extends FleetManagerError to integrate with the broader error hierarchy.
  */
-export declare class SchedulerError extends Error {
+export declare class SchedulerError extends FleetManagerError {
     constructor(message: string, options?: {
         cause?: Error;
+        code?: SchedulerErrorCode;
     });
 }
 /**
@@ -24,6 +50,60 @@ export declare class IntervalParseError extends SchedulerError {
         cause?: Error;
     });
 }
+/**
+ * Cron field definitions for validation and error messages
+ */
+export interface CronFieldInfo {
+    name: string;
+    index: number;
+    min: number;
+    max: number;
+    example: string;
+}
+/**
+ * Cron field definitions
+ */
+export declare const CRON_FIELDS: CronFieldInfo[];
+/**
+ * Error thrown when a cron expression cannot be parsed
+ *
+ * This error provides detailed information about what went wrong during parsing,
+ * including the invalid expression, which field is invalid, and examples of valid
+ * expressions.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   parseCronExpression("0 25 * * *");
+ * } catch (error) {
+ *   if (error instanceof CronParseError) {
+ *     console.error(error.message);
+ *     // CronParseError: Invalid cron expression "0 25 * * *" - hour must be 0-23
+ *     //   Example valid expression: "0 9 * * *" (daily at 9:00 AM)
+ *   }
+ * }
+ * ```
+ */
+export declare class CronParseError extends SchedulerError {
+    /** The original cron expression that failed to parse */
+    readonly expression: string;
+    /** The field that caused the error, if identifiable */
+    readonly field?: string;
+    /** A suggested valid example */
+    readonly example?: string;
+    constructor(message: string, expression: string, options?: {
+        cause?: Error;
+        field?: string;
+        example?: string;
+    });
+    /**
+     * Build a detailed error message with examples
+     */
+    static buildMessage(expression: string, reason: string, example?: {
+        expression: string;
+        description: string;
+    }): string;
+}
 /**
  * Error thrown when a schedule trigger fails during execution
  *

package/dist/scheduler/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/scheduler/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAKzD;AAMD;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,qDAAqD;IACrD,SAAgB,KAAK,EAAE,MAAM,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAKxE;AAMD;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,mDAAmD;IACnD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,2CAA2C;IAC3C,SAAgB,YAAY,EAAE,MAAM,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAO9B;AAMD;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,kEAAkE;IAClE,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAElC,+EAA+E;IAC/E,SAAgB,eAAe,EAAE,MAAM,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAOzE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/scheduler/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EAElB,MAAM,4BAA4B,CAAC;AAMpC;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;CAOrB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAM/D;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,iBAAiB;gBAEjD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,kBAAkB,CAAA;KAAE;CASzD;AAMD;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,qDAAqD;IACrD,SAAgB,KAAK,EAAE,MAAM,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAKxE;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,EAMtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,wDAAwD;IACxD,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,uDAAuD;IACvD,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAE/B,gCAAgC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;gBAG/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAS/D;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GACpD,MAAM;CAOV;AAMD;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,mDAAmD;IACnD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,2CAA2C;IAC3C,SAAgB,YAAY,EAAE,MAAM,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAO9B;AAMD;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,kEAAkE;IAClE,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAElC,+EAA+E;IAC/E,SAAgB,eAAe,EAAE,MAAM,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAOzE"}

package/dist/scheduler/errors.js

@@ -3,17 +3,37 @@
  *
  * Provides typed errors with descriptive messages for scheduler operations.
  */
+import { FleetManagerError, FleetManagerErrorCode, } from "../fleet-manager/errors.js";
+// =============================================================================
+// Error Codes
+// =============================================================================
+/**
+ * Error codes for scheduler errors (extends FleetManagerErrorCode)
+ */
+export const SchedulerErrorCode = {
+    ...FleetManagerErrorCode,
+    // Scheduler-specific error codes
+    CRON_PARSE_ERROR: "CRON_PARSE_ERROR",
+    INTERVAL_PARSE_ERROR: "INTERVAL_PARSE_ERROR",
+    SCHEDULE_TRIGGER_ERROR: "SCHEDULE_TRIGGER_ERROR",
+    SCHEDULER_SHUTDOWN_ERROR: "SCHEDULER_SHUTDOWN_ERROR",
+};
 // =============================================================================
 // Base Error Class
 // =============================================================================
 /**
  * Base error class for all scheduler errors
+ *
+ * Extends FleetManagerError to integrate with the broader error hierarchy.
  */
-export class SchedulerError extends Error {
+export class SchedulerError extends FleetManagerError {
     constructor(message, options) {
-        super(message);
+        super(message, {
+            cause: options?.cause,
+            // Use type assertion since SchedulerErrorCode is a superset of FleetManagerErrorCode
+            code: (options?.code ?? FleetManagerErrorCode.FLEET_MANAGER_ERROR),
+        });
         this.name = "SchedulerError";
-        this.cause = options?.cause;
     }
 }
 // =============================================================================
@@ -29,11 +49,66 @@ export class IntervalParseError extends SchedulerError {
     /** The original input string that failed to parse */
     input;
     constructor(message, input, options) {
-        super(message, options);
+        super(message, { cause: options?.cause, code: SchedulerErrorCode.INTERVAL_PARSE_ERROR });
         this.name = "IntervalParseError";
         this.input = input;
     }
 }
+/**
+ * Cron field definitions
+ */
+export const CRON_FIELDS = [
+    { name: "minute", index: 0, min: 0, max: 59, example: "0" },
+    { name: "hour", index: 1, min: 0, max: 23, example: "9" },
+    { name: "day-of-month", index: 2, min: 1, max: 31, example: "1" },
+    { name: "month", index: 3, min: 1, max: 12, example: "*" },
+    { name: "day-of-week", index: 4, min: 0, max: 7, example: "*" },
+];
+/**
+ * Error thrown when a cron expression cannot be parsed
+ *
+ * This error provides detailed information about what went wrong during parsing,
+ * including the invalid expression, which field is invalid, and examples of valid
+ * expressions.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   parseCronExpression("0 25 * * *");
+ * } catch (error) {
+ *   if (error instanceof CronParseError) {
+ *     console.error(error.message);
+ *     // CronParseError: Invalid cron expression "0 25 * * *" - hour must be 0-23
+ *     //   Example valid expression: "0 9 * * *" (daily at 9:00 AM)
+ *   }
+ * }
+ * ```
+ */
+export class CronParseError extends SchedulerError {
+    /** The original cron expression that failed to parse */
+    expression;
+    /** The field that caused the error, if identifiable */
+    field;
+    /** A suggested valid example */
+    example;
+    constructor(message, expression, options) {
+        super(message, { cause: options?.cause, code: SchedulerErrorCode.CRON_PARSE_ERROR });
+        this.name = "CronParseError";
+        this.expression = expression;
+        this.field = options?.field;
+        this.example = options?.example;
+    }
+    /**
+     * Build a detailed error message with examples
+     */
+    static buildMessage(expression, reason, example) {
+        let message = `Invalid cron expression "${expression}" - ${reason}`;
+        if (example) {
+            message += `\n  Example valid expression: "${example.expression}" (${example.description})`;
+        }
+        return message;
+    }
+}
 // =============================================================================
 // Schedule Trigger Errors
 // =============================================================================
@@ -51,7 +126,7 @@ export class ScheduleTriggerError extends SchedulerError {
     /** The name of the schedule that failed */
     scheduleName;
     constructor(message, agentName, scheduleName, options) {
-        super(message, options);
+        super(message, { cause: options?.cause, code: SchedulerErrorCode.SCHEDULE_TRIGGER_ERROR });
         this.name = "ScheduleTriggerError";
         this.agentName = agentName;
         this.scheduleName = scheduleName;
@@ -72,7 +147,7 @@ export class SchedulerShutdownError extends SchedulerError {
     /** Number of jobs that were still running when shutdown completed/timed out */
     runningJobCount;
     constructor(message, options) {
-        super(message, { cause: options.cause });
+        super(message, { cause: options.cause, code: SchedulerErrorCode.SCHEDULER_SHUTDOWN_ERROR });
         this.name = "SchedulerShutdownError";
         this.timedOut = options.timedOut;
         this.runningJobCount = options.runningJobCount;

package/dist/scheduler/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/scheduler/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe,EAAE,OAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAC9B,CAAC;CACF;AAED,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,qDAAqD;IACrC,KAAK,CAAS;IAE9B,YAAY,OAAe,EAAE,KAAa,EAAE,OAA2B;QACrE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD,mDAAmD;IACnC,SAAS,CAAS;IAElC,2CAA2C;IAC3B,YAAY,CAAS;IAErC,YACE,OAAe,EACf,SAAiB,EACjB,YAAoB,EACpB,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,kEAAkE;IAClD,QAAQ,CAAU;IAElC,+EAA+E;IAC/D,eAAe,CAAS;IAExC,YACE,OAAe,EACf,OAAsE;QAEtE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IACjD,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/scheduler/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAEpC,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,GAAG,qBAAqB;IACxB,iCAAiC;IACjC,gBAAgB,EAAE,kBAAkB;IACpC,oBAAoB,EAAE,sBAAsB;IAC5C,sBAAsB,EAAE,wBAAwB;IAChD,wBAAwB,EAAE,0BAA0B;CAC5C,CAAC;AAKX,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,iBAAiB;IACnD,YACE,OAAe,EACf,OAAsD;QAEtD,KAAK,CAAC,OAAO,EAAE;YACb,KAAK,EAAE,OAAO,EAAE,KAAK;YACrB,qFAAqF;YACrF,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,IAAI,qBAAqB,CAAC,mBAAmB,CAA0B;SAC5F,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,qDAAqD;IACrC,KAAK,CAAS;IAE9B,YAAY,OAAe,EAAE,KAAa,EAAE,OAA2B;QACrE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,oBAAoB,EAAE,CAAC,CAAC;QACzF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAiBD;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE;IAC3D,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE;IACzD,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE;IACjE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE;IAC1D,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE;CAChE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,cAAe,SAAQ,cAAc;IAChD,wDAAwD;IACxC,UAAU,CAAS;IAEnC,uDAAuD;IACvC,KAAK,CAAU;IAE/B,gCAAgC;IAChB,OAAO,CAAU;IAEjC,YACE,OAAe,EACf,UAAkB,EAClB,OAA6D;QAE7D,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,UAAkB,EAClB,MAAc,EACd,OAAqD;QAErD,IAAI,OAAO,GAAG,4BAA4B,UAAU,OAAO,MAAM,EAAE,CAAC;QACpE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,IAAI,kCAAkC,OAAO,CAAC,UAAU,MAAM,OAAO,CAAC,WAAW,GAAG,CAAC;QAC9F,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD,mDAAmD;IACnC,SAAS,CAAS;IAElC,2CAA2C;IAC3B,YAAY,CAAS;IAErC,YACE,OAAe,EACf,SAAiB,EACjB,YAAoB,EACpB,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,sBAAsB,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,kEAAkE;IAClD,QAAQ,CAAU;IAElC,+EAA+E;IAC/D,eAAe,CAAS;IAExC,YACE,OAAe,EACf,OAAsE;QAEtE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,wBAAwB,EAAE,CAAC,CAAC;QAC5F,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IACjD,CAAC;CACF"}

package/dist/scheduler/index.d.ts

@@ -6,6 +6,7 @@
  */
 export * from "./errors.js";
 export { parseInterval, calculateNextTrigger, isScheduleDue, } from "./interval.js";
+export { parseCronExpression, getNextCronTrigger, calculateNextCronTrigger, isValidCronExpression, type ParsedCronExpression, type CronParseOptions, } from "./cron.js";
 export { getScheduleState, updateScheduleState, getAgentScheduleStates, type ScheduleStateLogger, type ScheduleStateOptions, type ScheduleStateUpdates, } from "./schedule-state.js";
 export type { SchedulerOptions, SchedulerStatus, SchedulerState, SchedulerLogger, ScheduleCheckResult, ScheduleSkipReason, TriggerInfo, SchedulerTriggerCallback, AgentScheduleInfo, StopOptions, } from "./types.js";
 export { Scheduler } from "./scheduler.js";

package/dist/scheduler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,aAAa,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,aAAa,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC"}