@onmars/lunar-core 0.1.0

package/src/lib/config.ts

@@ -0,0 +1,202 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import { log } from './logger'
+
+/**
+ * Lunar configuration.
+ * Loaded from .env file + environment variables.
+ *
+ * Secrets and credentials live here (.env).
+ * Non-sensitive config (channels, moons, security) lives in config.yaml.
+ */
+export interface LunarConfig {
+  /** Project root directory (or CWD for npm-installed users) */
+  rootDir: string
+
+  /** Moon workspace directory */
+  moonWorkspace: string
+
+  /** Runtime data directory (sessions.db, PID file, logs). Defaults to moonWorkspace. */
+  dataDir: string
+
+  /**
+   * Discord bot token.
+   * @deprecated Use platforms.discord.token in config.yaml instead.
+   * Kept for backward compat — if platforms section exists, this is ignored.
+   */
+  discordToken?: string
+  /**
+   * Allowed Discord user IDs.
+   * @deprecated Use platforms.discord.allowedUsers in config.yaml instead.
+   */
+  discordAllowedUsers?: string[]
+  /**
+   * Discord guild ID.
+   * @deprecated Use platforms.discord.guild in config.yaml instead.
+   */
+  discordGuildId?: string
+
+  /** Agent backend to use */
+  agentBackend: 'claude' | 'codex' | 'ollama'
+
+  /** Brain API URL (for long-term memory) */
+  brainUrl?: string
+
+  /** ElevenLabs API key */
+  elevenlabsApiKey?: string
+  /** ElevenLabs voice ID */
+  elevenlabsVoiceId?: string
+
+  /** Log level */
+  logLevel: string
+  /** Development mode */
+  dev: boolean
+}
+
+/**
+ * Find the project root by looking for package.json with workspaces.
+ * Returns null if not found (user installed via npm, not cloned repo).
+ */
+function findProjectRoot(startDir: string): string | null {
+  let dir = startDir
+  for (let i = 0; i < 10; i++) {
+    const pkgPath = resolve(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(require('node:fs').readFileSync(pkgPath, 'utf-8'))
+        if (pkg.workspaces || pkg.name === 'lunar') {
+          return dir
+        }
+      } catch {}
+    }
+    const parent = resolve(dir, '..')
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * Load .env file manually into process.env.
+ * Doesn't override existing env vars (env > file).
+ * Returns true if the file was found and loaded.
+ */
+function loadEnvFile(filePath: string): boolean {
+  if (!existsSync(filePath)) return false
+
+  const content = require('node:fs').readFileSync(filePath, 'utf-8') as string
+  let loaded = 0
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+
+    const eqIndex = trimmed.indexOf('=')
+    if (eqIndex === -1) continue
+
+    const key = trimmed.slice(0, eqIndex).trim()
+    let value = trimmed.slice(eqIndex + 1).trim()
+
+    // Strip surrounding quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+
+    // Don't override existing env vars
+    if (!(key in process.env)) {
+      process.env[key] = value
+      loaded++
+    }
+  }
+
+  return loaded > 0 || true // File exists = loaded
+}
+
+/**
+ * Load configuration from environment variables.
+ *
+ * .env search order (first found wins, vars don't override):
+ *   1. Environment variables already set (Docker, systemd, export)
+ *   2. .env in CWD
+ *   3. .env in workspace (~/.lunar/.env)
+ *   4. .env in project root (for repo developers)
+ */
+export function loadConfig(rootDir?: string): LunarConfig {
+  const cwd = process.cwd()
+  const workspace = resolve(process.env.MOON_WORKSPACE ?? resolve(homedir(), '.lunar'))
+  const projectRoot = rootDir ?? findProjectRoot(cwd)
+
+  // Load .env files in priority order (later files don't override earlier ones)
+  const envSources: Array<{ path: string; label: string }> = [
+    { path: resolve(cwd, '.env'), label: 'cwd' },
+    { path: resolve(workspace, '.env'), label: 'workspace' },
+  ]
+
+  if (projectRoot) {
+    envSources.push({ path: resolve(projectRoot, '.env'), label: 'project-root' })
+  }
+
+  const loadedFrom: string[] = []
+  for (const source of envSources) {
+    if (loadEnvFile(source.path)) {
+      loadedFrom.push(source.label)
+      log.debug({ path: source.path, source: source.label }, 'Loaded .env file')
+    }
+  }
+
+  if (loadedFrom.length === 0) {
+    log.warn(
+      {
+        searched: envSources.map((s) => s.path),
+      },
+      'No .env file found — relying on environment variables only',
+    )
+  } else {
+    log.info({ sources: loadedFrom }, 'Configuration loaded from .env')
+  }
+
+  // Helper functions
+  const env = (key: string, fallback?: string): string => {
+    const raw = process.env[key]
+    const val = raw !== undefined && raw !== '' ? raw : fallback
+    if (val === undefined || val === '') {
+      throw new Error(
+        `Missing required environment variable: ${key}\nSet it in your environment, or create a .env file in one of:\n${envSources.map((s) => `  - ${s.path}`).join('\n')}`,
+      )
+    }
+    return val
+  }
+
+  const envOptional = (key: string): string | undefined => {
+    const val = process.env[key]
+    return val !== undefined && val !== '' ? val : undefined
+  }
+
+  const envList = (key: string, fallback: string[] = []): string[] => {
+    const val = process.env[key]
+    if (!val) return fallback
+    return val
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+  }
+
+  return {
+    rootDir: projectRoot ?? cwd,
+    moonWorkspace: workspace,
+    dataDir: resolve(envOptional('LUNAR_DATA_DIR') ?? workspace, 'store'),
+    discordToken: envOptional('DISCORD_TOKEN'),
+    discordAllowedUsers: envList('DISCORD_ALLOWED_USERS'),
+    discordGuildId: envOptional('DISCORD_GUILD_ID'),
+    agentBackend: (envOptional('AGENT_BACKEND') ?? 'claude') as LunarConfig['agentBackend'],
+    brainUrl: envOptional('BRAIN_URL'),
+    elevenlabsApiKey: envOptional('ELEVENLABS_API_KEY'),
+    elevenlabsVoiceId: envOptional('ELEVENLABS_VOICE_ID'),
+    logLevel: envOptional('LOG_LEVEL') ?? 'info',
+    dev: envOptional('NODE_ENV') === 'development' || process.argv.includes('--dev'),
+  }
+}

package/src/lib/cron-parser.ts

@@ -0,0 +1,388 @@
+//
+// Cron Parser — Zero-dependency cron expression parser.
+//
+// Spec: Standard 5-field cron format
+//   minute (0-59) hour (0-23) day-of-month (1-31) month (1-12) day-of-week (0-7, 0=7=Sun)
+//
+// Supports:
+//   - Exact values: 45 6 * * 1
+//   - Ranges: 0 9-17 * * *
+//   - Lists: 0,15,30,45 * * * *
+//   - Steps: */15 * * * *  (and range/steps: 1-5/2)
+//   - Wildcards: *
+//   - Day names: MON-FRI, SUN, etc.
+//   - Month names: JAN-DEC
+//
+// Not supported (v0.3 simplicity):
+//   - 6-field (seconds)
+//   - @yearly, @monthly aliases
+//   - L, W, # (Quartz extensions)
+//
+// Timezone support via Intl.DateTimeFormat.
+//
+
+const DAY_NAMES: Record<string, number> = {
+  SUN: 0,
+  MON: 1,
+  TUE: 2,
+  WED: 3,
+  THU: 4,
+  FRI: 5,
+  SAT: 6,
+}
+
+const MONTH_NAMES: Record<string, number> = {
+  JAN: 1,
+  FEB: 2,
+  MAR: 3,
+  APR: 4,
+  MAY: 5,
+  JUN: 6,
+  JUL: 7,
+  AUG: 8,
+  SEP: 9,
+  OCT: 10,
+  NOV: 11,
+  DEC: 12,
+}
+
+/** Parsed cron expression — each field is a Set of allowed values */
+export interface CronFields {
+  minutes: Set<number>
+  hours: Set<number>
+  daysOfMonth: Set<number>
+  months: Set<number>
+  daysOfWeek: Set<number>
+}
+
+/**
+ * Parse a single cron field into a Set of allowed integer values.
+ *
+ * @param field - The field string (e.g., "1-5", "star/15", "0,30")
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @param nameMap - Optional name->number mapping (days, months)
+ */
+export function parseField(
+  field: string,
+  min: number,
+  max: number,
+  nameMap?: Record<string, number>,
+): Set<number> {
+  const result = new Set<number>()
+
+  // Replace names with numbers (case-insensitive)
+  let resolved = field.toUpperCase()
+  if (nameMap) {
+    for (const [name, num] of Object.entries(nameMap)) {
+      resolved = resolved.replace(new RegExp(name, 'g'), String(num))
+    }
+  }
+
+  // Split on comma for lists: "1,3,5" or "1-3,7"
+  const parts = resolved.split(',')
+
+  for (const part of parts) {
+    // Check for step: "*/2" or "1-5/2"
+    const [rangePart, stepStr] = part.split('/')
+    const step = stepStr ? Number.parseInt(stepStr, 10) : 1
+
+    if (Number.isNaN(step) || step < 1) {
+      throw new Error(`Invalid step value in cron field: ${field}`)
+    }
+
+    if (rangePart === '*') {
+      // Wildcard with optional step
+      for (let i = min; i <= max; i += step) {
+        result.add(i)
+      }
+    } else if (rangePart.includes('-')) {
+      // Range: "1-5" or "MON-FRI"
+      const [startStr, endStr] = rangePart.split('-')
+      const start = Number.parseInt(startStr, 10)
+      const end = Number.parseInt(endStr, 10)
+
+      if (Number.isNaN(start) || Number.isNaN(end)) {
+        throw new Error(`Invalid range in cron field: ${field}`)
+      }
+      if (start < min || end > max) {
+        throw new Error(`Range ${start}-${end} out of bounds [${min}-${max}] in: ${field}`)
+      }
+
+      for (let i = start; i <= end; i += step) {
+        result.add(i)
+      }
+    } else {
+      // Single value
+      const val = Number.parseInt(rangePart, 10)
+      if (Number.isNaN(val)) {
+        throw new Error(`Invalid value in cron field: ${field}`)
+      }
+      if (val < min || val > max) {
+        throw new Error(`Value ${val} out of bounds [${min}-${max}] in: ${field}`)
+      }
+      result.add(val)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Parse a 5-field cron expression into structured fields.
+ *
+ * @param expr - Cron expression string (e.g., "45 6 * * 1-5")
+ * @returns Parsed fields with Sets of allowed values
+ * @throws Error if the expression is invalid
+ */
+export function parseCron(expr: string): CronFields {
+  const parts = expr.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression: expected 5 fields, got ${parts.length} in "${expr}"`)
+  }
+
+  const [minuteField, hourField, domField, monthField, dowField] = parts
+
+  // Parse day-of-week: normalize 7 -> 0 (both mean Sunday)
+  const rawDow = parseField(dowField, 0, 7, DAY_NAMES)
+  const daysOfWeek = new Set<number>()
+  for (const d of rawDow) {
+    daysOfWeek.add(d === 7 ? 0 : d)
+  }
+
+  return {
+    minutes: parseField(minuteField, 0, 59),
+    hours: parseField(hourField, 0, 23),
+    daysOfMonth: parseField(domField, 1, 31),
+    months: parseField(monthField, 1, 12, MONTH_NAMES),
+    daysOfWeek,
+  }
+}
+
+/**
+ * Get the components of a Date in a specific timezone.
+ * Uses Intl.DateTimeFormat for timezone conversion.
+ */
+function getDateInTz(
+  date: Date,
+  tz: string,
+): {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+  dow: number
+} {
+  const fmt = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+    weekday: 'short',
+    hour12: false,
+  })
+
+  const parts = fmt.formatToParts(date)
+  const get = (type: string) => {
+    const p = parts.find((p) => p.type === type)
+    return p ? Number.parseInt(p.value, 10) : 0
+  }
+
+  const weekdayStr = parts.find((p) => p.type === 'weekday')?.value ?? 'Sun'
+  const dowMap: Record<string, number> = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+  }
+
+  // Intl may return hour=24 for midnight in some locales
+  let hour = get('hour')
+  if (hour === 24) hour = 0
+
+  return {
+    year: get('year'),
+    month: get('month'),
+    day: get('day'),
+    hour,
+    minute: get('minute'),
+    dow: dowMap[weekdayStr] ?? 0,
+  }
+}
+
+/**
+ * Create a Date from timezone-local components.
+ * Finds the UTC instant that corresponds to the given local time.
+ */
+function createDateInTz(
+  year: number,
+  month: number,
+  day: number,
+  hour: number,
+  minute: number,
+  tz: string,
+): Date {
+  // Start with a UTC estimate
+  const estimate = new Date(Date.UTC(year, month - 1, day, hour, minute, 0, 0))
+
+  // Get the offset by comparing what the estimate looks like in the target TZ
+  const local = getDateInTz(estimate, tz)
+
+  // Compute offset: how many minutes ahead/behind is the TZ vs our estimate
+  const diffMinutes = local.hour * 60 + local.minute - (hour * 60 + minute)
+
+  // Handle day boundary crossings
+  let adjustMs = diffMinutes * 60 * 1000
+  if (local.day !== day) {
+    // Day wrapped -- large offset (e.g., crossing midnight)
+    if (local.day > day || local.month > month) {
+      adjustMs += 24 * 60 * 60 * 1000
+    } else {
+      adjustMs -= 24 * 60 * 60 * 1000
+    }
+  }
+
+  return new Date(estimate.getTime() - adjustMs)
+}
+
+/** Maximum iterations to prevent infinite loops in nextOccurrence */
+const MAX_ITERATIONS = 366 * 24 // ~1 year of hours (skipping optimizations avoid minute-level iteration)
+
+/**
+ * Compute the next occurrence of a cron expression after a reference time.
+ *
+ * Algorithm: Starting from refTime + 1 minute (rounded to minute boundary),
+ * iterate forward checking each component against the parsed fields.
+ * Optimized: skips forward by month/day/hour when possible instead of
+ * iterating minute by minute.
+ *
+ * @param fields - Parsed cron fields
+ * @param refTime - Reference time (Date or ms timestamp)
+ * @param tz - Timezone string (default: 'UTC')
+ * @returns Next matching Date, or null if none found within ~1 year
+ */
+export function nextOccurrence(
+  fields: CronFields,
+  refTime: Date | number,
+  tz = 'UTC',
+): Date | null {
+  const ref = typeof refTime === 'number' ? new Date(refTime) : refTime
+
+  // Start from next minute (ceiling to minute boundary)
+  let cursor = new Date(ref.getTime())
+  cursor.setUTCSeconds(0, 0)
+  cursor = new Date(cursor.getTime() + 60_000) // +1 minute
+
+  for (let i = 0; i < MAX_ITERATIONS; i++) {
+    const t = getDateInTz(cursor, tz)
+
+    // Check month
+    if (!fields.months.has(t.month)) {
+      // Skip to first day of next matching month
+      const nextMonth = getNextInSet(fields.months, t.month)
+      if (nextMonth !== null && nextMonth > t.month) {
+        cursor = createDateInTz(t.year, nextMonth, 1, 0, 0, tz)
+      } else {
+        // Wrap to next year
+        const firstMonth = Math.min(...fields.months)
+        cursor = createDateInTz(t.year + 1, firstMonth, 1, 0, 0, tz)
+      }
+      continue
+    }
+
+    // Check day-of-month AND day-of-week
+    // Standard cron behavior:
+    //   - Both wildcard: any day matches
+    //   - Only one restricted: that one must match
+    //   - Both restricted: either matching is sufficient (OR)
+    const domMatch = fields.daysOfMonth.has(t.day)
+    const dowMatch = fields.daysOfWeek.has(t.dow)
+
+    const domIsWildcard = fields.daysOfMonth.size === 31
+    const dowIsWildcard = fields.daysOfWeek.size === 7
+
+    let dayMatch: boolean
+    if (domIsWildcard && dowIsWildcard) {
+      dayMatch = true
+    } else if (domIsWildcard) {
+      dayMatch = dowMatch
+    } else if (dowIsWildcard) {
+      dayMatch = domMatch
+    } else {
+      // Both restricted -> OR (standard cron behavior)
+      dayMatch = domMatch || dowMatch
+    }
+
+    if (!dayMatch) {
+      // Skip to next day
+      cursor = createDateInTz(t.year, t.month, t.day + 1, 0, 0, tz)
+      continue
+    }
+
+    // Check hour
+    if (!fields.hours.has(t.hour)) {
+      const nextHour = getNextInSet(fields.hours, t.hour)
+      if (nextHour !== null && nextHour > t.hour) {
+        cursor = createDateInTz(t.year, t.month, t.day, nextHour, 0, tz)
+      } else {
+        // Skip to next day
+        cursor = createDateInTz(t.year, t.month, t.day + 1, 0, 0, tz)
+      }
+      continue
+    }
+
+    // Check minute
+    if (!fields.minutes.has(t.minute)) {
+      const nextMinute = getNextInSet(fields.minutes, t.minute)
+      if (nextMinute !== null && nextMinute > t.minute) {
+        cursor = createDateInTz(t.year, t.month, t.day, t.hour, nextMinute, tz)
+      } else {
+        // Skip to next hour
+        cursor = createDateInTz(t.year, t.month, t.day, t.hour + 1, 0, tz)
+      }
+      continue
+    }
+
+    // All fields match!
+    return cursor
+  }
+
+  return null // No match within iteration limit
+}
+
+/**
+ * Get the next value in a Set that is strictly greater than `current`.
+ * Returns null if no such value exists.
+ */
+function getNextInSet(set: Set<number>, current: number): number | null {
+  let best: number | null = null
+  for (const v of set) {
+    if (v > current && (best === null || v < best)) {
+      best = v
+    }
+  }
+  return best
+}
+
+/**
+ * Convenience: parse a cron expression and compute the next occurrence.
+ *
+ * @param expr - Cron expression string
+ * @param refTime - Reference time (default: now)
+ * @param tz - Timezone (default: 'UTC')
+ * @returns Next matching Date, or null if none found
+ */
+export function nextCron(
+  expr: string,
+  refTime: Date | number = new Date(),
+  tz = 'UTC',
+): Date | null {
+  const fields = parseCron(expr)
+  return nextOccurrence(fields, refTime, tz)
+}