@xelauvas/xela-cli 0.1.0

package/src/utils/cron.ts

@@ -0,0 +1,308 @@
+// Minimal cron expression parsing and next-run calculation.
+//
+// Supports the standard 5-field cron subset:
+//   minute hour day-of-month month day-of-week
+//
+// Field syntax: wildcard, N, step (star-slash-N), range (N-M), list (N,M,...).
+// No L, W, ?, or name aliases. All times are interpreted in the process's
+// local timezone — "0 9 * * *" means 9am wherever the CLI is running.
+
+export type CronFields = {
+  minute: number[]
+  hour: number[]
+  dayOfMonth: number[]
+  month: number[]
+  dayOfWeek: number[]
+}
+
+type FieldRange = { min: number; max: number }
+
+const FIELD_RANGES: FieldRange[] = [
+  { min: 0, max: 59 }, // minute
+  { min: 0, max: 23 }, // hour
+  { min: 1, max: 31 }, // dayOfMonth
+  { min: 1, max: 12 }, // month
+  { min: 0, max: 6 }, // dayOfWeek (0=Sunday; 7 accepted as Sunday alias)
+]
+
+// Parse a single cron field into a sorted array of matching values.
+// Supports: wildcard, N, star-slash-N (step), N-M (range), and comma-lists.
+// Returns null if invalid.
+function expandField(field: string, range: FieldRange): number[] | null {
+  const { min, max } = range
+  const out = new Set<number>()
+
+  for (const part of field.split(',')) {
+    // wildcard or star-slash-N
+    const stepMatch = part.match(/^\*(?:\/(\d+))?$/)
+    if (stepMatch) {
+      const step = stepMatch[1] ? parseInt(stepMatch[1], 10) : 1
+      if (step < 1) return null
+      for (let i = min; i <= max; i += step) out.add(i)
+      continue
+    }
+
+    // N-M or N-M/S
+    const rangeMatch = part.match(/^(\d+)-(\d+)(?:\/(\d+))?$/)
+    if (rangeMatch) {
+      const lo = parseInt(rangeMatch[1]!, 10)
+      const hi = parseInt(rangeMatch[2]!, 10)
+      const step = rangeMatch[3] ? parseInt(rangeMatch[3], 10) : 1
+      // dayOfWeek: accept 7 as Sunday alias in ranges (e.g. 5-7 = Fri,Sat,Sun → [5,6,0])
+      const isDow = min === 0 && max === 6
+      const effMax = isDow ? 7 : max
+      if (lo > hi || step < 1 || lo < min || hi > effMax) return null
+      for (let i = lo; i <= hi; i += step) {
+        out.add(isDow && i === 7 ? 0 : i)
+      }
+      continue
+    }
+
+    // plain N
+    const singleMatch = part.match(/^\d+$/)
+    if (singleMatch) {
+      let n = parseInt(part, 10)
+      // dayOfWeek: accept 7 as Sunday alias → 0
+      if (min === 0 && max === 6 && n === 7) n = 0
+      if (n < min || n > max) return null
+      out.add(n)
+      continue
+    }
+
+    return null
+  }
+
+  if (out.size === 0) return null
+  return Array.from(out).sort((a, b) => a - b)
+}
+
+/**
+ * Parse a 5-field cron expression into expanded number arrays.
+ * Returns null if invalid or unsupported syntax.
+ */
+export function parseCronExpression(expr: string): CronFields | null {
+  const parts = expr.trim().split(/\s+/)
+  if (parts.length !== 5) return null
+
+  const expanded: number[][] = []
+  for (let i = 0; i < 5; i++) {
+    const result = expandField(parts[i]!, FIELD_RANGES[i]!)
+    if (!result) return null
+    expanded.push(result)
+  }
+
+  return {
+    minute: expanded[0]!,
+    hour: expanded[1]!,
+    dayOfMonth: expanded[2]!,
+    month: expanded[3]!,
+    dayOfWeek: expanded[4]!,
+  }
+}
+
+/**
+ * Compute the next Date strictly after `from` that matches the cron fields,
+ * using the process's local timezone. Walks forward minute-by-minute. Bounded
+ * at 366 days; returns null if no match (impossible for valid cron, but
+ * satisfies the type).
+ *
+ * Standard cron semantics: when both dayOfMonth and dayOfWeek are constrained
+ * (neither is the full range), a date matches if EITHER matches.
+ *
+ * DST: fixed-hour crons targeting a spring-forward gap (e.g. `30 2 * * *`
+ * in a US timezone) skip the transition day — the gap hour never appears
+ * in local time, so the hour-set check fails and the loop moves on.
+ * Wildcard-hour crons (`30 * * * *`) fire at the first valid minute after
+ * the gap. Fall-back repeats fire once (the step-forward logic jumps past
+ * the second occurrence). This matches vixie-cron behavior.
+ */
+export function computeNextCronRun(
+  fields: CronFields,
+  from: Date,
+): Date | null {
+  const minuteSet = new Set(fields.minute)
+  const hourSet = new Set(fields.hour)
+  const domSet = new Set(fields.dayOfMonth)
+  const monthSet = new Set(fields.month)
+  const dowSet = new Set(fields.dayOfWeek)
+
+  // Is the field wildcarded (full range)?
+  const domWild = fields.dayOfMonth.length === 31
+  const dowWild = fields.dayOfWeek.length === 7
+
+  // Round up to the next whole minute (strictly after `from`)
+  const t = new Date(from.getTime())
+  t.setSeconds(0, 0)
+  t.setMinutes(t.getMinutes() + 1)
+
+  const maxIter = 366 * 24 * 60
+  for (let i = 0; i < maxIter; i++) {
+    const month = t.getMonth() + 1
+    if (!monthSet.has(month)) {
+      // Jump to start of next month
+      t.setMonth(t.getMonth() + 1, 1)
+      t.setHours(0, 0, 0, 0)
+      continue
+    }
+
+    const dom = t.getDate()
+    const dow = t.getDay()
+    // When both dom/dow are constrained, either match is sufficient (OR semantics)
+    const dayMatches =
+      domWild && dowWild
+        ? true
+        : domWild
+          ? dowSet.has(dow)
+          : dowWild
+            ? domSet.has(dom)
+            : domSet.has(dom) || dowSet.has(dow)
+
+    if (!dayMatches) {
+      // Jump to start of next day
+      t.setDate(t.getDate() + 1)
+      t.setHours(0, 0, 0, 0)
+      continue
+    }
+
+    if (!hourSet.has(t.getHours())) {
+      t.setHours(t.getHours() + 1, 0, 0, 0)
+      continue
+    }
+
+    if (!minuteSet.has(t.getMinutes())) {
+      t.setMinutes(t.getMinutes() + 1)
+      continue
+    }
+
+    return t
+  }
+
+  return null
+}
+
+// --- cronToHuman ------------------------------------------------------------
+// Intentionally narrow: covers common patterns; falls through to the raw cron
+// string for anything else. The `utc` option exists for CCR remote triggers
+// (agents-platform.tsx), which run on servers and always use UTC cron strings
+// — that path translates UTC→local for display and needs midnight-crossing
+// logic for the weekday case. Local scheduled tasks (the default) need neither.
+
+const DAY_NAMES = [
+  'Sunday',
+  'Monday',
+  'Tuesday',
+  'Wednesday',
+  'Thursday',
+  'Friday',
+  'Saturday',
+]
+
+function formatLocalTime(minute: number, hour: number): string {
+  // January 1 — no DST gap anywhere. Using `new Date()` (today) would roll
+  // 2am→3am on the one spring-forward day per year.
+  const d = new Date(2000, 0, 1, hour, minute)
+  return d.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' })
+}
+
+function formatUtcTimeAsLocal(minute: number, hour: number): string {
+  // Create a date in UTC and format in user's local timezone
+  const d = new Date()
+  d.setUTCHours(hour, minute, 0, 0)
+  return d.toLocaleTimeString('en-US', {
+    hour: 'numeric',
+    minute: '2-digit',
+    timeZoneName: 'short',
+  })
+}
+
+export function cronToHuman(cron: string, opts?: { utc?: boolean }): string {
+  const utc = opts?.utc ?? false
+  const parts = cron.trim().split(/\s+/)
+  if (parts.length !== 5) return cron
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts as [
+    string,
+    string,
+    string,
+    string,
+    string,
+  ]
+
+  // Every N minutes: step/N * * * *
+  const everyMinMatch = minute.match(/^\*\/(\d+)$/)
+  if (
+    everyMinMatch &&
+    hour === '*' &&
+    dayOfMonth === '*' &&
+    month === '*' &&
+    dayOfWeek === '*'
+  ) {
+    const n = parseInt(everyMinMatch[1]!, 10)
+    return n === 1 ? 'Every minute' : `Every ${n} minutes`
+  }
+
+  // Every hour: 0 * * * *
+  if (
+    minute.match(/^\d+$/) &&
+    hour === '*' &&
+    dayOfMonth === '*' &&
+    month === '*' &&
+    dayOfWeek === '*'
+  ) {
+    const m = parseInt(minute, 10)
+    if (m === 0) return 'Every hour'
+    return `Every hour at :${m.toString().padStart(2, '0')}`
+  }
+
+  // Every N hours: 0 step/N * * *
+  const everyHourMatch = hour.match(/^\*\/(\d+)$/)
+  if (
+    minute.match(/^\d+$/) &&
+    everyHourMatch &&
+    dayOfMonth === '*' &&
+    month === '*' &&
+    dayOfWeek === '*'
+  ) {
+    const n = parseInt(everyHourMatch[1]!, 10)
+    const m = parseInt(minute, 10)
+    const suffix = m === 0 ? '' : ` at :${m.toString().padStart(2, '0')}`
+    return n === 1 ? `Every hour${suffix}` : `Every ${n} hours${suffix}`
+  }
+
+  // --- Remaining cases reference hour+minute: branch on utc ----------------
+
+  if (!minute.match(/^\d+$/) || !hour.match(/^\d+$/)) return cron
+  const m = parseInt(minute, 10)
+  const h = parseInt(hour, 10)
+  const fmtTime = utc ? formatUtcTimeAsLocal : formatLocalTime
+
+  // Daily at specific time: M H * * *
+  if (dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
+    return `Every day at ${fmtTime(m, h)}`
+  }
+
+  // Specific day of week: M H * * D
+  if (dayOfMonth === '*' && month === '*' && dayOfWeek.match(/^\d$/)) {
+    const dayIndex = parseInt(dayOfWeek, 10) % 7 // normalize 7 (Sunday alias) -> 0
+    let dayName: string | undefined
+    if (utc) {
+      // UTC day+time may land on a different local day (midnight crossing).
+      // Compute the actual local weekday by constructing the UTC instant.
+      const ref = new Date()
+      const daysToAdd = (dayIndex - ref.getUTCDay() + 7) % 7
+      ref.setUTCDate(ref.getUTCDate() + daysToAdd)
+      ref.setUTCHours(h, m, 0, 0)
+      dayName = DAY_NAMES[ref.getDay()]
+    } else {
+      dayName = DAY_NAMES[dayIndex]
+    }
+    if (dayName) return `Every ${dayName} at ${fmtTime(m, h)}`
+  }
+
+  // Weekdays: M H * * 1-5
+  if (dayOfMonth === '*' && month === '*' && dayOfWeek === '1-5') {
+    return `Weekdays at ${fmtTime(m, h)}`
+  }
+
+  return cron
+}

package/src/utils/cronJitterConfig.ts

@@ -0,0 +1,75 @@
+// GrowthBook-backed cron jitter configuration.
+//
+// Separated from cronScheduler.ts so the scheduler can be bundled in the
+// Agent SDK public build without pulling in analytics/growthbook.ts and
+// its large transitive dependency set (settings/hooks/config cycle).
+//
+// Usage:
+//   REPL (useScheduledTasks.ts): pass `getJitterConfig: getCronJitterConfig`
+//   Daemon/SDK: omit getJitterConfig → DEFAULT_CRON_JITTER_CONFIG applies.
+
+import { z } from 'zod/v4'
+import { getFeatureValue_CACHED_WITH_REFRESH } from '../services/analytics/growthbook.js'
+import {
+  type CronJitterConfig,
+  DEFAULT_CRON_JITTER_CONFIG,
+} from './cronTasks.js'
+import { lazySchema } from './lazySchema.js'
+
+// How often to re-fetch tengu_kairos_cron_config from GrowthBook. Short because
+// this is an incident lever — when we push a config change to shed :00 load,
+// we want the fleet to converge within a minute, not on the next process
+// restart. The underlying call is a synchronous cache read; the refresh just
+// clears the memoized entry so the next read triggers a background fetch.
+const JITTER_CONFIG_REFRESH_MS = 60 * 1000
+
+// Upper bounds here are defense-in-depth against fat-fingered GrowthBook
+// pushes. Like pollConfig.ts, Zod rejects the whole object on any violation
+// rather than partially trusting it — a config with one bad field falls back
+// to DEFAULT_CRON_JITTER_CONFIG entirely. oneShotFloorMs shares oneShotMaxMs's
+// ceiling (floor > max would invert the jitter range) and is cross-checked in
+// the refine; the shared ceiling keeps the individual bound explicit in the
+// error path. recurringMaxAgeMs uses .default() so a pre-existing GB config
+// without the field doesn't get wholesale-rejected — the other fields were
+// added together at config inception and don't need this.
+const HALF_HOUR_MS = 30 * 60 * 1000
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000
+const cronJitterConfigSchema = lazySchema(() =>
+  z
+    .object({
+      recurringFrac: z.number().min(0).max(1),
+      recurringCapMs: z.number().int().min(0).max(HALF_HOUR_MS),
+      oneShotMaxMs: z.number().int().min(0).max(HALF_HOUR_MS),
+      oneShotFloorMs: z.number().int().min(0).max(HALF_HOUR_MS),
+      oneShotMinuteMod: z.number().int().min(1).max(60),
+      recurringMaxAgeMs: z
+        .number()
+        .int()
+        .min(0)
+        .max(THIRTY_DAYS_MS)
+        .default(DEFAULT_CRON_JITTER_CONFIG.recurringMaxAgeMs),
+    })
+    .refine(c => c.oneShotFloorMs <= c.oneShotMaxMs),
+)
+
+/**
+ * Read `tengu_kairos_cron_config` from GrowthBook, validate, fall back to
+ * defaults on absent/malformed/out-of-bounds config. Called from check()
+ * every tick via the `getJitterConfig` callback — cheap (synchronous cache
+ * hit). Refresh window: JITTER_CONFIG_REFRESH_MS.
+ *
+ * Exported so ops runbooks can point at a single function when documenting
+ * the lever, and so tests can spy on it without mocking GrowthBook itself.
+ *
+ * Pass this as `getJitterConfig` when calling createCronScheduler in REPL
+ * contexts. Daemon/SDK callers omit getJitterConfig and get defaults.
+ */
+export function getCronJitterConfig(): CronJitterConfig {
+  const raw = getFeatureValue_CACHED_WITH_REFRESH<unknown>(
+    'tengu_kairos_cron_config',
+    DEFAULT_CRON_JITTER_CONFIG,
+    JITTER_CONFIG_REFRESH_MS,
+  )
+  const parsed = cronJitterConfigSchema().safeParse(raw)
+  return parsed.success ? parsed.data : DEFAULT_CRON_JITTER_CONFIG
+}