@herdctl/core 0.0.1 → 0.1.0

package/src/scheduler/errors.ts

@@ -1,101 +0,0 @@
-/**
- * Error classes for scheduler module
- *
- * Provides typed errors with descriptive messages for scheduler operations.
- */
-
-// =============================================================================
-// Base Error Class
-// =============================================================================
-
-/**
- * Base error class for all scheduler errors
- */
-export class SchedulerError extends Error {
-  constructor(message: string, options?: { cause?: Error }) {
-    super(message);
-    this.name = "SchedulerError";
-    this.cause = options?.cause;
-  }
-}
-
-// =============================================================================
-// Interval Parse Errors
-// =============================================================================
-
-/**
- * Error thrown when an interval string cannot be parsed
- *
- * This error provides detailed information about what went wrong during parsing,
- * including the invalid input and suggestions for valid formats.
- */
-export class IntervalParseError extends SchedulerError {
-  /** The original input string that failed to parse */
-  public readonly input: string;
-
-  constructor(message: string, input: string, options?: { cause?: Error }) {
-    super(message, options);
-    this.name = "IntervalParseError";
-    this.input = input;
-  }
-}
-
-// =============================================================================
-// Schedule Trigger Errors
-// =============================================================================
-
-/**
- * Error thrown when a schedule trigger fails during execution
- *
- * This error wraps the underlying cause and provides context about which
- * agent and schedule encountered the error. It is used internally by the
- * Scheduler to capture and report trigger failures while allowing the
- * scheduler to continue processing other schedules.
- */
-export class ScheduleTriggerError extends SchedulerError {
-  /** The name of the agent that owns the schedule */
-  public readonly agentName: string;
-
-  /** The name of the schedule that failed */
-  public readonly scheduleName: string;
-
-  constructor(
-    message: string,
-    agentName: string,
-    scheduleName: string,
-    options?: { cause?: Error }
-  ) {
-    super(message, options);
-    this.name = "ScheduleTriggerError";
-    this.agentName = agentName;
-    this.scheduleName = scheduleName;
-  }
-}
-
-// =============================================================================
-// Scheduler Shutdown Errors
-// =============================================================================
-
-/**
- * Error thrown when scheduler shutdown encounters issues
- *
- * This error is thrown when the scheduler cannot shut down cleanly,
- * typically due to running jobs not completing within the configured timeout.
- */
-export class SchedulerShutdownError extends SchedulerError {
-  /** Whether the shutdown timed out waiting for jobs to complete */
-  public readonly timedOut: boolean;
-
-  /** Number of jobs that were still running when shutdown completed/timed out */
-  public readonly runningJobCount: number;
-
-  constructor(
-    message: string,
-    options: { timedOut: boolean; runningJobCount: number; cause?: Error }
-  ) {
-    super(message, { cause: options.cause });
-    this.name = "SchedulerShutdownError";
-    this.timedOut = options.timedOut;
-    this.runningJobCount = options.runningJobCount;
-  }
-}

package/src/scheduler/index.ts

@@ -1,53 +0,0 @@
-/**
- * Scheduler module for herdctl
- *
- * Provides interval parsing, scheduling utilities, and the Scheduler class
- * for agent fleet management.
- */
-
-// Errors
-export * from "./errors.js";
-
-// Interval parsing and scheduling
-export {
-  parseInterval,
-  calculateNextTrigger,
-  isScheduleDue,
-} from "./interval.js";
-
-// Schedule state management
-export {
-  getScheduleState,
-  updateScheduleState,
-  getAgentScheduleStates,
-  type ScheduleStateLogger,
-  type ScheduleStateOptions,
-  type ScheduleStateUpdates,
-} from "./schedule-state.js";
-
-// Scheduler types
-export type {
-  SchedulerOptions,
-  SchedulerStatus,
-  SchedulerState,
-  SchedulerLogger,
-  ScheduleCheckResult,
-  ScheduleSkipReason,
-  TriggerInfo,
-  SchedulerTriggerCallback,
-  AgentScheduleInfo,
-  StopOptions,
-} from "./types.js";
-
-// Scheduler class
-export { Scheduler } from "./scheduler.js";
-
-// Schedule runner
-export {
-  runSchedule,
-  buildSchedulePrompt,
-  type RunScheduleOptions,
-  type ScheduleRunResult,
-  type ScheduleRunnerLogger,
-  type TriggerMetadata,
-} from "./schedule-runner.js";

package/src/scheduler/interval.ts

@@ -1,189 +0,0 @@
-/**
- * Interval parsing utilities for the scheduler module
- *
- * Parses human-readable interval strings like "5m", "1h", "30s" into milliseconds.
- */
-
-import { IntervalParseError } from "./errors.js";
-
-/**
- * Multipliers to convert time units to milliseconds
- */
-const UNIT_MULTIPLIERS: Record<string, number> = {
-  s: 1000, // seconds
-  m: 60 * 1000, // minutes
-  h: 60 * 60 * 1000, // hours
-  d: 24 * 60 * 60 * 1000, // days
-};
-
-/**
- * Valid time units
- */
-const VALID_UNITS = Object.keys(UNIT_MULTIPLIERS);
-
-/**
- * Parse an interval string into milliseconds
- *
- * Supports the format `{number}{unit}` where:
- * - `number` is a positive integer
- * - `unit` is one of: s (seconds), m (minutes), h (hours), d (days)
- *
- * @param interval - The interval string to parse (e.g., "5m", "1h", "30s", "1d")
- * @returns The interval in milliseconds
- * @throws {IntervalParseError} If the interval string is invalid
- *
- * @example
- * parseInterval("5s")  // returns 5000
- * parseInterval("5m")  // returns 300000
- * parseInterval("1h")  // returns 3600000
- * parseInterval("1d")  // returns 86400000
- */
-export function parseInterval(interval: string): number {
-  // Handle empty string
-  if (!interval || interval.trim() === "") {
-    throw new IntervalParseError(
-      'Interval cannot be empty. Expected format: "{number}{unit}" where unit is s/m/h/d (e.g., "5m", "1h")',
-      interval
-    );
-  }
-
-  const trimmed = interval.trim();
-
-  // Match the pattern: optional whitespace, digits, optional whitespace, unit letter
-  const match = trimmed.match(/^(-?\d+)\s*([a-zA-Z]+)$/);
-
-  if (!match) {
-    // Check for common error patterns to provide better error messages
-    if (/^\d+$/.test(trimmed)) {
-      throw new IntervalParseError(
-        `Missing time unit in interval "${interval}". Expected format: "{number}{unit}" where unit is s/m/h/d (e.g., "5m", "1h")`,
-        interval
-      );
-    }
-
-    if (/^[a-zA-Z]+$/.test(trimmed)) {
-      throw new IntervalParseError(
-        `Missing numeric value in interval "${interval}". Expected format: "{number}{unit}" where unit is s/m/h/d (e.g., "5m", "1h")`,
-        interval
-      );
-    }
-
-    if (/\d+\.\d+/.test(trimmed)) {
-      throw new IntervalParseError(
-        `Decimal values are not supported in interval "${interval}". Use integers only (e.g., "5m" instead of "5.5m")`,
-        interval
-      );
-    }
-
-    throw new IntervalParseError(
-      `Invalid interval format "${interval}". Expected format: "{number}{unit}" where unit is s/m/h/d (e.g., "5m", "1h")`,
-      interval
-    );
-  }
-
-  const [, valueStr, unit] = match;
-  const value = parseInt(valueStr, 10);
-  const normalizedUnit = unit.toLowerCase();
-
-  // Check for negative numbers
-  if (value < 0) {
-    throw new IntervalParseError(
-      `Negative intervals are not allowed: "${interval}". Use a positive integer value`,
-      interval
-    );
-  }
-
-  // Check for zero
-  if (value === 0) {
-    throw new IntervalParseError(
-      `Zero interval is not allowed: "${interval}". Use a positive integer value`,
-      interval
-    );
-  }
-
-  // Check for valid unit
-  if (!VALID_UNITS.includes(normalizedUnit)) {
-    throw new IntervalParseError(
-      `Invalid time unit "${unit}" in interval "${interval}". Valid units are: s (seconds), m (minutes), h (hours), d (days)`,
-      interval
-    );
-  }
-
-  return value * UNIT_MULTIPLIERS[normalizedUnit];
-}
-
-/**
- * Calculate the next trigger time for a schedule
- *
- * @param lastCompletedAt - When the schedule last completed, or null for first run
- * @param interval - The interval string (e.g., "5m", "1h")
- * @param jitterPercent - Optional jitter percentage (0-10) to add randomness and prevent thundering herd
- * @returns The next trigger time as a Date
- *
- * @example
- * // First run - triggers immediately
- * calculateNextTrigger(null, "5m") // returns now
- *
- * // Subsequent run - triggers after interval
- * calculateNextTrigger(new Date("2024-01-01T00:00:00Z"), "5m")
- * // returns 2024-01-01T00:05:00Z (plus optional jitter)
- *
- * // With jitter to prevent thundering herd
- * calculateNextTrigger(lastRun, "1h", 5) // adds 0-5% jitter to interval
- */
-export function calculateNextTrigger(
-  lastCompletedAt: Date | null,
-  interval: string,
-  jitterPercent?: number
-): Date {
-  const now = new Date();
-
-  // If no previous run, trigger immediately
-  if (lastCompletedAt === null) {
-    return now;
-  }
-
-  const intervalMs = parseInterval(interval);
-
-  // Calculate jitter if specified
-  let jitterMs = 0;
-  if (jitterPercent !== undefined && jitterPercent > 0) {
-    // Clamp jitter to 0-10%
-    const clampedJitter = Math.min(Math.max(jitterPercent, 0), 10);
-    // Random jitter between 0 and clampedJitter% of interval
-    jitterMs = Math.floor(Math.random() * (intervalMs * clampedJitter) / 100);
-  }
-
-  const nextTrigger = new Date(lastCompletedAt.getTime() + intervalMs + jitterMs);
-
-  // Handle clock skew: if next trigger is in the past, trigger now
-  if (nextTrigger.getTime() < now.getTime()) {
-    return now;
-  }
-
-  return nextTrigger;
-}
-
-/**
- * Check if a schedule is due to run
- *
- * @param nextRunAt - The scheduled next run time
- * @param now - Optional current time (defaults to new Date())
- * @returns true if the schedule is due (nextRunAt <= now)
- *
- * @example
- * const nextRun = new Date("2024-01-01T00:05:00Z");
- *
- * // Before scheduled time
- * isScheduleDue(nextRun, new Date("2024-01-01T00:04:00Z")) // false
- *
- * // At scheduled time
- * isScheduleDue(nextRun, new Date("2024-01-01T00:05:00Z")) // true
- *
- * // After scheduled time
- * isScheduleDue(nextRun, new Date("2024-01-01T00:06:00Z")) // true
- */
-export function isScheduleDue(nextRunAt: Date, now?: Date): boolean {
-  const currentTime = now ?? new Date();
-  return nextRunAt.getTime() <= currentTime.getTime();
-}