Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.1 KB
Raw Blame
/**
 * Timezone utilities for scheduling
 *
 * All scheduling runs in the user's configured timezone.
 * The server process uses TZ=UTC, so all Date operations are UTC internally.
 * These helpers convert between UTC and the user's local timezone.
 */

const WEEKDAY_MAP = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 }

// Cache Intl.DateTimeFormat instances per timezone — these are expensive to construct
// but safe to reuse since they're stateless formatters.
const formatterCache = new Map()

function getFormatter(timezone) {
  let fmt = formatterCache.get(timezone)
  if (!fmt) {
    fmt = new Intl.DateTimeFormat('en-US', {
      timeZone: timezone,
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
      hour: '2-digit',
      minute: '2-digit',
      weekday: 'short',
      hour12: false
    })
    formatterCache.set(timezone, fmt)
  }
  return fmt
}

/**
 * Get local date/time parts for a UTC Date in the given timezone.
 * @param {Date} utcDate - Date object (interpreted as UTC since TZ=UTC)
 * @param {string} timezone - IANA timezone string
 * @returns {{ year: number, month: number, day: number, hour: number, minute: number, dayOfWeek: number }}
 */
export function getLocalParts(utcDate, timezone) {
  const parts = {}
  for (const { type, value } of getFormatter(timezone).formatToParts(utcDate)) {
    parts[type] = value
  }
  return {
    year: parseInt(parts.year),
    month: parseInt(parts.month),
    day: parseInt(parts.day),
    hour: parts.hour === '24' ? 0 : parseInt(parts.hour),
    minute: parseInt(parts.minute),
    dayOfWeek: WEEKDAY_MAP[parts.weekday] ?? 0
  }
}

/**
 * Get the UTC offset (in ms) for a timezone at a given UTC time.
 * Positive = ahead of UTC (e.g., +9h for Tokyo), negative = behind (e.g., -7h for PDT).
 *
 * Callers doing DST-safe midnight anchoring (`anchorLocalMidnightUtc` below)
 * re-sample this at their candidate instant because the offset can change
 * between the approximate UTC time and the target local boundary.
 * @param {Date} utcDate - Reference UTC date
 * @param {string} timezone - IANA timezone string
 * @returns {number} Offset in milliseconds
 */
export function getUtcOffsetMs(utcDate, timezone) {
  const utcStr = utcDate.toLocaleString('en-US', { timeZone: 'UTC' })
  const localStr = utcDate.toLocaleString('en-US', { timeZone: timezone })
  return new Date(localStr).getTime() - new Date(utcStr).getTime()
}

/**
 * Find the next UTC timestamp where the local time in `timezone` matches HH:MM.
 * @param {number} afterMs - UTC timestamp to search after
 * @param {number} hours - Target hour (0-23) in local timezone
 * @param {number} minutes - Target minute (0-59) in local timezone
 * @param {string} timezone - IANA timezone string
 * @returns {number} UTC timestamp
 */
export function nextLocalTime(afterMs, hours, minutes, timezone) {
  // Start from the after point, find what the current local time is
  const ref = new Date(afterMs)
  const local = getLocalParts(ref, timezone)

  // Compute desired vs current in minutes-since-midnight
  const desiredMin = hours * 60 + minutes
  const currentMin = local.hour * 60 + local.minute

  // How many minutes until the target time?
  let deltaMin = desiredMin - currentMin
  if (deltaMin < 0) deltaMin += 1440 // wrap to next day

  const candidate = afterMs + deltaMin * 60_000
  // DST transitions can shift the result by up to ±60 min — verify and nudge if needed.
  const check = getLocalParts(new Date(candidate), timezone)
  const checkMin = check.hour * 60 + check.minute
  if (checkMin !== desiredMin) {
    return candidate + (desiredMin - checkMin) * 60_000
  }
  return candidate
}

/**
 * Get the date string (YYYY-MM-DD) for an instant in the user's timezone —
 * "today" by default, or a caller-supplied instant. Pass the SAME instant a
 * writer stamped into its `timestamp`/`startedAt` so the day key and the instant
 * can't land on different days across a midnight boundary (issue #2681).
 * @param {string} timezone - IANA timezone string
 * @param {Date} [atDate] - instant to key (defaults to now)
 * @returns {string}
 */
export function todayInTimezone(timezone, atDate = new Date()) {
  const parts = getLocalParts(atDate, timezone)
  return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}`
}

/**
 * Does a UTC timestamp fall on the given "YYYY-MM-DD" LOCAL calendar day?
 *
 * The question every day-scoped "did this already happen today" gate asks: a
 * record carries a precise UTC instant, the day bucket it must be compared
 * against is a local calendar day, and for any negative-UTC-offset zone the two
 * disagree for several hours around the rollover. Keyed through
 * `todayInTimezone` so the record's day and the scheduler's "today" are derived
 * by one rule rather than two that must stay byte-identical.
 *
 * A missing or unparseable timestamp answers false — "no evidence it happened
 * today" — rather than throwing, because every caller is a guard deciding
 * whether to stay quiet.
 */
export function isLocalDay(timestamp, timezone, dayStr) {
  if (!timestamp) return false
  const at = new Date(timestamp)
  if (Number.isNaN(at.getTime())) return false
  return todayInTimezone(timezone, at) === dayStr
}

const DAY_MS = 24 * 60 * 60 * 1000
const LOCAL_DAY_SEARCH_RADIUS_MS = 36 * 60 * 60 * 1000

function parseIsoDay(dayStr) {
  const normalized = String(dayStr || '').trim()
  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(normalized)
  if (!match || Number(match[1]) === 0) return null
  const utcMs = Date.parse(`${normalized}T00:00:00Z`)
  if (!Number.isFinite(utcMs) || new Date(utcMs).toISOString().slice(0, 10) !== normalized) return null
  const [, year, month, day] = match.map(Number)
  return { normalized, utcMs, ordinal: year * 10_000 + month * 100 + day }
}

function localDayOrdinalAt(utcMs, timezone) {
  const { year, month, day } = getLocalParts(new Date(utcMs), timezone)
  return year * 10_000 + month * 100 + day
}

function findLocalDayBoundary(parsed, tz) {
  // Keep the common path cheap: offset refinement lands exactly on midnight
  // for ordinary days and transitions that happen later in the day.
  const firstOffset = getUtcOffsetMs(new Date(parsed.utcMs), tz)
  const candidate = parsed.utcMs - firstOffset
  const refinedOffset = getUtcOffsetMs(new Date(candidate), tz)
  const refined = parsed.utcMs - refinedOffset
  const refinedParts = getLocalParts(new Date(refined), tz)
  const refinedOrdinal = refinedParts.year * 10_000 + refinedParts.month * 100 + refinedParts.day
  if (
    refinedOrdinal === parsed.ordinal
    && refinedParts.hour === 0
    && refinedParts.minute === 0
    && localDayOrdinalAt(refined - 1, tz) < parsed.ordinal
  ) {
    return refined
  }

  // Midnight-offset arithmetic can oscillate across a transition that occurs
  // at 00:00. Local calendar dates remain ordered across UTC instants, so find
  // the first instant whose local date is not before the requested date.
  let low = parsed.utcMs - LOCAL_DAY_SEARCH_RADIUS_MS
  let high = parsed.utcMs + LOCAL_DAY_SEARCH_RADIUS_MS
  if (localDayOrdinalAt(low, tz) >= parsed.ordinal || localDayOrdinalAt(high, tz) < parsed.ordinal) return NaN
  while (low < high) {
    const mid = low + Math.floor((high - low) / 2)
    if (localDayOrdinalAt(mid, tz) < parsed.ordinal) low = mid + 1
    else high = mid
  }
  return low
}

/**
 * UTC timestamp (ms) of the first instant belonging to the `YYYY-MM-DD`
 * local day in `tz`. This is normally local midnight. When a timezone jumps
 * forward at 00:00 and midnight does not exist, it is the first representable
 * instant on that date rather than an instant from the previous local day.
 * @param {string} dayStr - Local day as `YYYY-MM-DD`
 * @param {string} tz - IANA timezone string
 * @returns {number} UTC timestamp (ms), or `NaN` for an invalid or skipped date
 */
export function anchorLocalMidnightUtc(dayStr, tz) {
  const parsed = parseIsoDay(dayStr)
  if (!parsed) return NaN
  const boundary = findLocalDayBoundary(parsed, tz)
  return Number.isFinite(boundary) && localDayOrdinalAt(boundary, tz) === parsed.ordinal
    ? boundary
    : NaN
}

/**
 * The user's current local calendar day expressed as UTC ISO bounds — the
 * shared "today's events" query window (calendar agenda route, voice
 * calendar_today tool). `startDate` is local midnight; `endDate` is
 * 23:59:59.999 later.
 * @param {string} timezone - IANA timezone string
 * @param {Date} [atDate] - instant to key (defaults to now)
 * @returns {{ date: string, startDate: string, endDate: string }}
 */
export function localDayWindowUtc(timezone, atDate = new Date()) {
  const date = todayInTimezone(timezone, atDate)
  const startMs = anchorLocalMidnightUtc(date, timezone)
  const range = localDayRangeUtc(date, timezone)
  const endMs = range?.end?.getTime()
  return {
    date,
    startDate: new Date(startMs).toISOString(),
    // The inclusive end is derived from the next local-day boundary, so a
    // 23-hour or 25-hour DST day cannot leak into or omit the adjacent date.
    endDate: new Date(Number.isFinite(endMs) ? endMs - 1 : startMs + DAY_MS - 1).toISOString(),
  }
}

/**
 * UTC `[start, end)` instants that bound a local calendar day (`YYYY-MM-DD`)
 * in `timezone`. The end is the next local date's boundary rather than a
 * fixed 24 hours after the start, preserving 23- and 25-hour DST days.
 * This remains separate from `localDayWindowUtc`, whose inclusive end serves
 * callers with a different boundary contract.
 *
 * @param {string} dateStr - Local day as `YYYY-MM-DD`
 * @param {string} timezone - IANA timezone string
 * @returns {{ start: Date, end: Date } | null}
 */
export function localDayRangeUtc(dateStr, timezone) {
  const parsed = parseIsoDay(dateStr)
  if (!parsed) return null
  const startMs = anchorLocalMidnightUtc(parsed.normalized, timezone)
  // A timezone can skip a complete calendar date when it crosses the date
  // line. That is not a valid local-day range, even though the next boundary
  // is well-defined for the preceding day's end.
  if (!Number.isFinite(startMs) || localDayOrdinalAt(startMs, timezone) !== parsed.ordinal) return null

  // ISO arithmetic avoids Date.UTC's special 1900 offset for years 00–99.
  const nextDate = new Date(parsed.utcMs + DAY_MS).toISOString().slice(0, 10)
  const nextParsed = parseIsoDay(nextDate)
  const endMs = nextParsed ? findLocalDayBoundary(nextParsed, timezone) : NaN
  if (!Number.isFinite(endMs)) return null
  return { start: new Date(startMs), end: new Date(endMs) }
}

// ---------------------------------------------------------------------------
// HH:MM time-window primitives
//
// Two consumers validate "HH:MM" (24h) strings with deliberately different
// strictness, so both regexes live here as the single source of truth:
//   - HHMM_RE (lenient): tolerates a single-digit hour ("9:00") as well as
//     the zero-padded form. Used by voice quiet-hours (routes/voice.js via
//     proactiveSpeech.js), which has always accepted single-digit hours.
//   - HHMM_STRICT_RE: requires a zero-padded hour ("09:00"). Used by the
//     dashboard activateWindow validator (services/dashboardLayouts.js) and
//     mirrored client-side in client/src/utils/timeWindow.js — keep all three
//     in sync (each has a parity test against the literal pattern).
// ---------------------------------------------------------------------------
export const HHMM_RE = /^([01]?\d|2[0-3]):([0-5]\d)$/
export const HHMM_STRICT_RE = /^([01]\d|2[0-3]):[0-5]\d$/

// Parse "HH:MM" → minutes-from-midnight. Lenient (accepts single-digit hours)
// so callers can validate strictness separately at their boundary. Returns
// null for malformed input so the caller can fall through or error.
export function parseHHMM(s) {
  if (typeof s !== 'string') return null
  const m = s.match(HHMM_RE)
  if (!m) return null
  return Number(m[1]) * 60 + Number(m[2])
}

// Half-open [start, end) window-inclusion check against minutes-from-midnight.
// Handles the overnight case (start > end, e.g. 22:00 → 07:00) by wrapping.
// start === end is an empty window → never matches. Malformed bounds → false
// (caller treats as "window off"). Shared by voice quiet-hours and mirrored
// client-side for dashboard time-windowed layout auto-activation.
export function isWithinTimeWindow({ start, end, nowMinutes }) {
  const s = parseHHMM(start)
  const e = parseHHMM(end)
  if (s === null || e === null) return false
  if (s === e) return false
  if (s < e) return nowMinutes >= s && nowMinutes < e
  // Overnight wrap: in-window if at-or-after start OR before end.
  return nowMinutes >= s || nowMinutes < e
}

// "HH:MM" → the daily cron expression ("M H * * *") that fires at that local
// wall-clock time. STRICT on purpose (zero-padded hour): the value comes from
// a user-editable reminder setting, and a malformed one must be visible as a
// refusal to schedule rather than silently rounded into some other slot — so
// this returns null and the caller cancels instead of registering a bad cron.
// Shared by every daily-reminder scheduler (POST, autobiography) so two of
// them cannot drift on what "09:00" registers as.
export function dailyCronFromHHMM(time) {
  if (typeof time !== 'string' || !HHMM_STRICT_RE.test(time)) return null
  const [hour, minute] = time.split(':').map(Number)
  return `${minute} ${hour} * * *`
}